Errors
Every API error has the same format. Decide by the HTTP status and by the code in error: both are stable. The message text is for a person to read and may change.
The body is { "error": "code", "message": "text" }, and some errors carry extra fields that say what to do. A validation refusal (400, invalid_request) carries campos: a list where each item has the refused campo and the motivo. The value you sent never comes back in the answer.
404 is also used for a resource that exists but is not yours: the API does not confirm the existence of another customer’s resource, not even through the status.
The Errors guide explains what to do in each case, with code to retry on 429 and 503.
By HTTP status#
| HTTP status | Description |
|---|---|
400 | The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal. |
401 | The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which. |
403 | The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed. |
404 | The resource does not exist, or is not yours. The two answers are identical, byte for byte. |
409 | The request is well formed, but the resource state does not allow it. The error field says which case it is. |
410 | The connect link expired or was already used. The error field says which of the two. |
413 | The file is over the size ceiling, which is the same for every customer. |
415 | The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes. |
422 | The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal. |
429 | Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key. |
503 | The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one. |
By error code#
| Error code (error) | HTTP status | When it happens | Routes |
|---|---|---|---|
invalid_request | 400 | Field refused, with the reason | 73 |
invalid_reset_token | 400 | Invalid reset link | 2 |
unauthorized | 401 | Key refused | 77 |
account_blocked | 403 | Account blocked by Helsen | 25 |
connection_not_released | 403 | Account not yet released to connect | 4 |
forbidden | 403 | Insufficient scope | 76 |
test_key_not_allowed | 403 | Test key on a route outside test mode | 74 |
trial_expired | 403 | Free trial ended | 25 |
not_found | 404 | Does not exist, or is not yours | 49 |
account_at_capacity | 409 | The account that requested the link reached its maximum of numbers | 1 |
already_requeued | 409 | Item already requeued | 1 |
idempotency_key_reused | 409 | Idempotency-Key used with another body | 1 |
link_not_open | 409 | Link that is not open | 1 |
media_not_ready | 409 | Media not fetched yet | 2 |
message_not_cancelable | 409 | Message that already left the queue | 1 |
no_webhook_endpoint | 409 | No active webhook endpoint | 1 |
not_available_in_coexistence | 409 | Unavailable in coexistence | 2 |
number_capacity_reached | 409 | The account is already at its number capacity | 4 |
number_disconnected | 409 | Number disconnected from Luna | 10 |
pin_not_applicable | 409 | The number does not ask for a PIN | 1 |
reconnect_not_applicable | 409 | The authorization does not allow reconnection | 2 |
register_budget_reserved | 409 | Registration attempts reserved | 1 |
template_content_unknown | 409 | Luna does not know the template content | 1 |
template_not_approved | 409 | Template that is not approved yet | 1 |
webhook_endpoint_limit | 409 | Endpoint limit | 1 |
window_closed | 409 | Service window closed | 1 |
link_expired | 410 | Link expired | 1 |
link_used | 410 | Link already used | 2 |
file_too_large | 413 | File over the ceiling | 2 |
unsupported_media_type | 415 | Content type not read | 33 |
meta_rejected | 422 | Meta refused the operation | 9 |
management_busy | 429 | Account management busy | 14 |
number_rate_limited | 429 | Number pace | 2 |
queue_full | 429 | Send queue full | 1 |
rate_limited | 429 | Request limit | 88 |
unavailable | 503 | Unavailable | 88 |