API and webhooks
API errors
The format of XBASE API errors, what each HTTP status means and the list of stable codes for your integration to handle.
Updated on
Every API error response has the same format. Handle the error by the HTTP status and the code: the message text explains the problem, but it can change.
Format
{
"statusCode": 401,
"timestamp": "2026-11-04T16:03:56.074Z",
"path": "/api/external/v1/me",
"method": "GET",
"message": "Chave de API inválida ou revogada.",
"code": "INVALID_API_KEY"
}| Field | Description |
|---|---|
statusCode | HTTP status |
message | What went wrong, as text |
code | Stable error code. Validation errors (400) have no code |
details | Extra data for some errors, like details.metaCode (the error code at Meta) and details.reason |
timestamp · path · method | When and on which route |
HTTP status
| Status | Means |
|---|---|
| 200 · 204 | It worked (204 has no body) |
| 400 | Invalid request: a field is missing or breaks a rule. The message lists the fields |
| 401 | Key missing, invalid or revoked |
| 403 | The key does not have the route's scope |
| 404 | The resource does not exist in this workspace |
| 422 | Meta rejected it, the action breaks a WhatsApp rule (like the 24-hour window) or the resource is not ready for it |
| 5xx | Error in XBASE. Try again after a few seconds |
Codes
code | Status | When |
|---|---|---|
INVALID_API_KEY | 401 | No Authorization header, or the key has the wrong format, does not exist or was revoked |
MISSING_SCOPE | 403 | The key does not have the route's scope |
NOT_INCOMING_MESSAGE | 400 | Only a message received from the contact can be marked as read |
NUMBER_NOT_FOUND | 404 | The WhatsApp number (numberId) is not from this workspace |
TEMPLATE_NOT_FOUND | 404 | The template does not exist for this number |
MESSAGE_NOT_FOUND | 404 | The message (messageId) is not from a WhatsApp conversation in this workspace |
FLOW_NOT_FOUND | 404 | The Flow does not belong to the number's WhatsApp account |
NOT_FOUND | 404 | The Instagram account (connectionId) is not from this workspace |
NUMBER_DISCONNECTED | 422 | The WhatsApp number is disconnected |
WINDOW_CLOSED | 422 | WhatsApp free-form message outside the 24-hour window. details.reason says why |
UNSUPPORTED_FOR_NUMBER | 422 | The number does not accept this kind of send |
SEND_REJECTED | 422 | XBASE refused the send before Meta, for example, missing template variables. The message says why |
META_ERROR | 422 | Meta rejected the action on WhatsApp or Instagram. On WhatsApp, details.metaCode has Meta's code |
Good practices
- Handle errors by
codeand status, not by themessagetext. - On
5xx, try again with increasing waits (for example, 2, 10 and 30 seconds). - Do not repeat a WhatsApp send that returned
200: the contact already received it. The API does not prevent duplicate sends. - On
WINDOW_CLOSED, do not retry the same message: send a template and wait for the contact to reply. - On
401, check that the key was not revoked in Integrations → API keys.