# Erreurs et limites de débit

> Index de la documentation : https://wahasend.com/docs/fr/llms.txt · Tout en un fichier : https://wahasend.com/docs/fr.md · URL de base de l'API : https://app.wahasend.com/api/v1

Chaque erreur répond avec la même enveloppe et un en-tête `X-Request-Id` :

400 VALIDATION_ERROR:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed. Check the details for specific field errors.",
    "details": { "phone": ["Invalid recipient. Use an international phone number (e.g. +22212345678) or a WhatsApp id ending in @lid."] },
    "issues": [{ "field": "phone", "code": "custom", "message": "Invalid recipient. …" }],
    "requestId": "7c9e2f4a-1b3d-4e5f-8a6b-0c1d2e3f4a5b"
  }
}
```

- `code` est stable : testez-le, jamais `message` (le texte peut changer).
- `details` ajoute des faits quand il y en a (`retryAfterSeconds`, `attemptsRemaining`, `products`…). `issues` liste chaque champ incorrect d'un `VALIDATION_ERROR` avec un code comme `required`, `too_big` (avec `maximum`) ou `invalid_uuid`.
- `requestId` (le même que l'en-tête `X-Request-Id`) : donnez-le au support, il nous permet de retrouver votre requête.
- Les réponses 429 et 503 portent `Retry-After` (secondes) quand l'attente est connue. Attendez ce temps avant de réessayer.
- 5xx : on peut réessayer une lecture. Avant de réessayer un envoi, vérifiez `GET /messages` : un délai dépassé a pu partir.

<a id="rate-limits"></a>

### Limites de débit

| Limite | Valeur | En cas de dépassement |
| --- | --- | --- |
| Modifications par organisation (POST, PUT, PATCH, DELETE ; lectures libres), partagées par toutes les clés et personnes | 300 par minute (pics jusqu'à 300) | 429 `RATE_LIMITED`, `details.scope: "organization"`, `retryAfterSeconds`, `limitPerMinute`, `Retry-After` |
| Envois de texte par numéro | 60 par minute (priorité `high` : sans plafond) | Mis en file, envoyés plus tard ; jamais refusés |
| Messages de campagne | 20 par minute par numéro, 60 par minute par organisation, espacés de 3 à 7 s | Mis en file, envoyés plus tard |
| Codes de vérification ([OTP](https://wahasend.com/docs/fr/errors.md#otp-limits)) | Par numéro : 1 toutes les 30 s, 3 par 10 min, 10 par 24 h ; 60 par minute par organisation | 429 `OTP_RATE_LIMITED`, `Retry-After` |
| Envois par IA via Connect (MCP) | Voir [limites d'envoi](https://wahasend.com/docs/fr/connect.md#connect-limits) | L'outil répond « non envoyé » avec la raison |
| Messages pendant l'[essai gratuit](https://wahasend.com/docs/fr/errors.md#trial-limits) | 100 par jour par organisation (jour UTC), tous les envois comptés | 429 `TRIAL_LIMIT_REACHED`, `details.limit`, `used`, `resetsAt`, `Retry-After` |
| Connexion | 20 essais par 15 min par adresse IP ; 10 mauvais mots de passe bloquent l'e-mail 15 min | 429 `RATE_LIMIT` / `TOO_MANY_LOGIN_ATTEMPTS` |
| Connexion Claude (OAuth) | Enregistrement 60/h par IP ; jeton 120 par 15 min par application ; autorisation et révocation 60 par 15 min | 429 `RATE_LIMIT` |

<a id="otp-limits"></a>

### Limites OTP

Pour que personne ne puisse se servir de votre formulaire d'inscription pour inonder un numéro de codes (et faire signaler votre numéro), `POST /otp/send` est limité par numéro de destination dans votre organisation : un code toutes les 30 secondes, 3 par 10 minutes et 10 par 24 heures ; et 60 codes par minute pour toute l'organisation. Les fenêtres sont glissantes (pas des minutes ni des jours calendaires). Au-delà, la réponse est 429 `OTP_RATE_LIMITED` avec `Retry-After` et `details` : `scope` (`phone` ou `organization`), `reason` (`cooldown`, `window`, `day` ou `organization`), `limit` et `retryAfterSeconds`. Indiquez à la personne quand elle peut redemander ; ne réessayez pas automatiquement.

<a id="trial-limits"></a>

### Limites de l'essai gratuit

Un nouveau compte a les produits demandés gratuitement pendant 7 jours (un essai par personne et par produit). Tant que tous les produits de l'organisation sont en essai, elle peut envoyer 100 messages par jour via WahaSend — envois simples, lots (chaque destinataire compte), campagnes (comptées au lancement), rappels, codes OTP, envois de médias, réponses de l'assistant et envois Connect ensemble — et son crédit IA est de 2 $ pour tout l'essai. Le compteur repart à 00:00 UTC. Un envoi qui ne rentre pas est refusé, rien n'est mis en file : 429 `TRIAL_LIMIT_REACHED` avec `Retry-After` (secondes jusqu'à minuit UTC) et `details` : `limit`, `used`, `requested`, `retryAfterSeconds`, `resetsAt`. Un lot ou une campagne plus grand que ce qui reste est refusé en entier. Dès qu'un produit est payé, la limite disparaît. À la fin de l'essai, le produit est en pause (403 `PRODUCT_REQUIRED`) jusqu'au paiement ; rien n'est supprimé.

<a id="error-codes"></a>

### Tous les codes d'erreur

Généré depuis le catalogue d'erreurs du serveur. Les codes ne sont jamais renommés ni supprimés ; de nouveaux peuvent apparaître.

#### VALIDATION_ERROR

HTTP 400 · Validation failed. Check the details for specific field errors.

#### INVALID_JSON

HTTP 400 · Request body contains invalid JSON.

#### INVALID_ID

HTTP 400 · Invalid identifier.

#### PAYLOAD_TOO_LARGE

HTTP 413 · The request is too large.

#### FILE_TOO_LARGE

HTTP 413 · The file is too large.

#### ROUTE_NOT_FOUND

HTTP 404 · This API route does not exist. Check /api for available endpoints.

#### NOT_FOUND

HTTP 404 · Not found.

#### CONFLICT

HTTP 409 · This resource already exists.

#### REFERENCE_ERROR

HTTP 400 · Referenced resource does not exist.

#### IN_USE

HTTP 409 · This is still used elsewhere and cannot be removed.

#### CONSTRAINT_VIOLATION

HTTP 400 · Operation violates a data constraint.

#### FORBIDDEN_ACTION

HTTP 400 · This action is not allowed.

#### RATE_LIMIT

HTTP 429 · Too many requests. Slow down and try again.

#### RATE_LIMITED

HTTP 429 · Your organization is sending too many requests. Wait a moment and try again.

#### AUTH_ERROR

HTTP 401 · Authentication required.

#### TOO_MANY_LOGIN_ATTEMPTS

HTTP 429 · Too many wrong passwords for this account. Try again in 15 minutes.

#### ACCOUNT_DEACTIVATED

HTTP 403 · Account is deactivated. Contact support.

#### OAUTH_TOKEN_SCOPE

HTTP 403 · This Claude connection can only be used by Claude (MCP endpoint).

#### OAUTH_REQUEST_INVALID

HTTP 400 · This request from Claude has expired or was already answered. Start again from Claude.

#### NUMBER_KEY_SCOPE

HTTP 403 · This API key belongs to one WhatsApp number and can only send and read through it.

#### USER_REQUIRED

HTTP 403 · Sign in to the dashboard to do this; API keys cannot.

#### WRONG_PASSWORD

HTTP 400 · The password is not correct.

#### NO_PASSWORD_SET

HTTP 400 · No password set. Ask the admin to reset your password.

#### INVALID_LINK

HTTP 400 · This link has expired or was already used. Ask for a new one.

#### SIGNUP_DISABLED

HTTP 403 · Sign-up is currently closed.

#### TWO_FACTOR_REQUIRED

HTTP 403 · This organization requires two-step sign-in. Turn it on in your account first.

#### TWO_FACTOR_CODE_INVALID

HTTP 400 · The code is not correct. Check your authenticator app and try again.

#### TWO_FACTOR_CHALLENGE_EXPIRED

HTTP 400 · This sign-in has expired. Enter your email and password again.

#### TWO_FACTOR_SETUP_EXPIRED

HTTP 400 · The set-up has expired. Start again.

#### TWO_FACTOR_ALREADY_ENABLED

HTTP 409 · Two-step sign-in is already on.

#### TWO_FACTOR_NOT_ENABLED

HTTP 409 · Two-step sign-in is not on.

#### TWO_FACTOR_OWNER_FIRST

HTTP 409 · Turn on two-step sign-in for your own account first.

#### TWO_FACTOR_UNAVAILABLE

HTTP 503 · Two-step sign-in is not available on this server yet.

#### COUNTRY_LOCKED

HTTP 409 · Your country can no longer be changed here once you have paid. Write to us to change it.

#### PRODUCT_REQUIRED

HTTP 403 · This feature is not included in your products.

#### NO_ACTIVE_PRODUCT

HTTP 403 · Your account has no active product yet. Contact us to activate one.

#### ADMIN_ONLY

HTTP 403 · This action is restricted to the platform admin.

#### ROLE_FORBIDDEN

HTTP 403 · Your role in this organization does not allow this. Ask an owner or admin.

#### ADMIN_CANNOT_DELETE

HTTP 403 · The platform admin organization cannot be deleted.

#### INVITE_INVALID

HTTP 400 · This invitation has expired, was cancelled or was already used. Ask for a new one.

#### INVITE_EMAIL_MISMATCH

HTTP 403 · This invitation was sent to another email address. Sign in with that address.

#### ALREADY_MEMBER

HTTP 409 · This person is already in your team.

#### TEAM_FULL

HTTP 409 · The team is full.

#### OWNER_ROLE_FIXED

HTTP 409 · The owner stays owner. Transfer the ownership first.

#### CANNOT_REMOVE_OWNER

HTTP 409 · The owner cannot be removed. Transfer the ownership first.

#### OWNER_CANNOT_LEAVE

HTTP 409 · You own this organization. Transfer the ownership before leaving.

#### LAST_ORGANIZATION

HTTP 409 · This is your only organization. Delete your account instead.

#### NOT_OWNER

HTTP 403 · Only the owner can do this.

#### ALREADY_OWNER

HTTP 409 · You already own this organization.

#### OWNS_ORGANIZATION

HTTP 409 · You own an organization. Transfer it to someone else first.

#### USE_LEAVE

HTTP 400 · Use "Leave this organization" to remove yourself.

#### TOO_MANY_ORGANIZATIONS

HTTP 409 · You can own up to 10 organizations.

#### NO_SESSION_CONFIGURED

HTTP 400 · This account has no connected WhatsApp number.

#### SESSION_NOT_CONNECTED

HTTP 409 · WhatsApp is not connected. Reconnect the number.

#### CONTAINER_NOT_FOUND

HTTP 404 · WhatsApp number not found.

#### NUMBER_LIMIT_REACHED

HTTP 403 · This account uses all the WhatsApp numbers it may have (Developer and Connect include 3). Add extra numbers, or remove a number.

#### PORT_EXHAUSTED

HTTP 503 · No room for a new WhatsApp number right now. Contact support.

#### NUMBER_NOT_ON_WHATSAPP

HTTP 400 · This number is not on WhatsApp.

#### NO_VALID_NUMBERS

HTTP 400 · None of these numbers are on WhatsApp.

#### NUMBER_ON_OTHER_ASSISTANT

HTTP 409 · This WhatsApp number already answers for another assistant that is on. Remove it there first, or turn that assistant off.

#### SECRETS_KEY_MISSING

HTTP 503 · SECRETS_ENCRYPTION_KEY must be set to give WhatsApp servers their own keys.

#### NUMBER_VALIDATION_UNAVAILABLE

HTTP 503 · Numbers cannot be checked right now. Try again shortly.

#### OTP_EXPIRED

HTTP 410 · OTP has expired. Request a new code.

#### OTP_ALREADY_VERIFIED

HTTP 400 · OTP has already been verified.

#### OTP_MAX_ATTEMPTS

HTTP 429 · Maximum verification attempts exceeded. Request a new code.

#### OTP_INVALID_CODE

HTTP 400 · Invalid code.

#### OTP_RATE_LIMITED

HTTP 429 · Too many verification codes for this number or this account. Wait before sending another one.

#### OTP_TEMPLATE_MISSING_CODE

HTTP 400 · The message template must contain {{code}}, where the code goes.

#### MESSAGE_NOT_FOUND

HTTP 404 · No message with this id was sent by this account.

#### MESSAGE_NOT_SENT

HTTP 409 · This message has not been sent yet (or it failed). Only sent messages can be edited or deleted.

#### MESSAGE_WRONG_NUMBER

HTTP 403 · This message was sent from another WhatsApp number than the one this request uses.

#### CAMPAIGN_INVALID_STATE

HTTP 400 · The campaign cannot do this in its current state.

#### STAFF_PHONE_LIMIT

HTTP 409 · You can add up to 10 phones for orders.

#### STAFF_PHONE_IS_BUSINESS

HTTP 400 · This is your business WhatsApp number. Add another phone: yours or a staff member's.

#### WEBHOOK_SIGNING_UNAVAILABLE

HTTP 503 · Webhook signing is not available on this server yet (SECRETS_ENCRYPTION_KEY is not set).

#### ATTACHMENT_NOT_FOUND

HTTP 404 · This message was not found in this chat, or it has no attachment.

#### ATTACHMENT_EXPIRED

HTTP 410 · This file is no longer on WhatsApp (older attachments expire). Ask the contact to send it again.

#### ATTACHMENT_TOO_LARGE

HTTP 413 · This file is too large to open here.

#### ATTACHMENT_UNSUPPORTED

HTTP 415 · This kind of file cannot be opened here.

#### TRANSCRIPTION_UNAVAILABLE

HTTP 503 · Voice notes cannot be read because speech-to-text is not enabled on this server.

#### SEND_FILE_TOO_LARGE

HTTP 413 · This file is too large to send on WhatsApp from here.

#### SEND_FILE_TYPE_NOT_ALLOWED

HTTP 415 · This kind of file cannot be sent. Photos, PDFs, Office files, text and CSV files, voice notes, audio and MP4 videos can.

#### SEND_FILE_URL_UNREACHABLE

HTTP 422 · The file at this link cannot be fetched. Use a public https link to the file itself.

#### WAHA_ERROR

HTTP 502 · WhatsApp could not complete the request. Try again.

#### WAHA_SESSION_ERROR

HTTP 503 · WhatsApp is not connected.

#### WAHA_UNREACHABLE

HTTP 503 · WhatsApp service is unreachable. Please try again later.

#### UPSTREAM_TIMEOUT

HTTP 504 · A service we depend on took too long to answer. Try again.

#### AI_UNAVAILABLE

HTTP 503 · The AI service is not available right now. Try again shortly.

#### AI_BUSY

HTTP 503 · The AI service is busy. Try again in a moment.

#### SERVICE_BUSY

HTTP 503 · The service is busy. Try again in a moment.

#### AI_QUOTA_EXCEEDED

HTTP 402 · This month's AI allowance is used up. It renews on the 1st, or contact us to raise it.

#### TRIAL_LIMIT_REACHED

HTTP 429 · Free trial: 100 messages a day. Activate your product to remove this limit.

#### PADDLE_NOT_CONFIGURED

HTTP 503 · Card payment is not available on this server. Use another way to pay.

#### PADDLE_NO_SUBSCRIPTION

HTTP 404 · This organization has no card payment to manage.

#### PADDLE_UNAVAILABLE

HTTP 502 · The card payment service did not answer. Try again in a moment.

#### PADDLE_SIGNATURE_INVALID

HTTP 401 · Invalid or expired Paddle signature.

#### PADDLE_CHANGE_REFUSED

HTTP 409 · This change could not be made. Check your card, or try again later.

#### PADDLE_NOTHING_TO_RESUME

HTTP 409 · This subscription is not set to stop: there is nothing to undo.

#### PADDLE_PERIOD_UNAVAILABLE

HTTP 409 · This billing period is not offered for this product.

#### PADDLE_SAME_PERIOD

HTTP 409 · This product is already billed this way.

#### INVOICE_NOT_AVAILABLE

HTTP 404 · No receipt to download for this payment.

#### INTERNAL_ERROR

HTTP 500 · An unexpected error occurred. Please try again or contact support.