LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Errors

Use with AI

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 statusDescription
400The 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.
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
403The 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.
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
409The request is well formed, but the resource state does not allow it. The error field says which case it is.
410The connect link expired or was already used. The error field says which of the two.
413The file is over the size ceiling, which is the same for every customer.
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
422The 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.
429Too 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.
503The 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 statusWhen it happensRoutes
invalid_request400Field refused, with the reason73
invalid_reset_token400Invalid reset link2
unauthorized401Key refused77
account_blocked403Account blocked by Helsen25
connection_not_released403Account not yet released to connect4
forbidden403Insufficient scope76
test_key_not_allowed403Test key on a route outside test mode74
trial_expired403Free trial ended25
not_found404Does not exist, or is not yours49
account_at_capacity409The account that requested the link reached its maximum of numbers1
already_requeued409Item already requeued1
idempotency_key_reused409Idempotency-Key used with another body1
link_not_open409Link that is not open1
media_not_ready409Media not fetched yet2
message_not_cancelable409Message that already left the queue1
no_webhook_endpoint409No active webhook endpoint1
not_available_in_coexistence409Unavailable in coexistence2
number_capacity_reached409The account is already at its number capacity4
number_disconnected409Number disconnected from Luna10
pin_not_applicable409The number does not ask for a PIN1
reconnect_not_applicable409The authorization does not allow reconnection2
register_budget_reserved409Registration attempts reserved1
template_content_unknown409Luna does not know the template content1
template_not_approved409Template that is not approved yet1
webhook_endpoint_limit409Endpoint limit1
window_closed409Service window closed1
link_expired410Link expired1
link_used410Link already used2
file_too_large413File over the ceiling2
unsupported_media_type415Content type not read33
meta_rejected422Meta refused the operation9
management_busy429Account management busy14
number_rate_limited429Number pace2
queue_full429Send queue full1
rate_limited429Request limit88
unavailable503Unavailable88