# Error codes

> Every error code the API answers: what happened, why, and how to fix it.

Source: https://docs.vlayers.ai/errors

A refused request answers a JSON body with an `error` code, a `message`, a `requestId`, whether it is `retryable`, and a `docs` link to the code's page. Authentication errors and the event and webhook routes answer a smaller body: `error` and `message`, sometimes `details`.

| Error | Status | What happened |
|---|---|---|
| [`invalid_request`](https://docs.vlayers.ai/errors/invalid_request) | 400 | The request is not valid |
| [`invalid_idempotency_key`](https://docs.vlayers.ai/errors/invalid_idempotency_key) | 400 | The Idempotency-Key header is malformed |
| [`unauthorized`](https://docs.vlayers.ai/errors/unauthorized) | 401 | No valid API key |
| [`insufficient_scope`](https://docs.vlayers.ai/errors/insufficient_scope) | 403 | The key does not cover this |
| [`no_project`](https://docs.vlayers.ai/errors/no_project) | 403 | The request names no workspace |
| [`sms_refused`](https://docs.vlayers.ai/errors/sms_refused) | 403, 429 | The text was refused by the SMS rules |
| [`wallet_refused`](https://docs.vlayers.ai/errors/wallet_refused) | 402 | The balance cannot cover this message |
| [`not_found`](https://docs.vlayers.ai/errors/not_found) | 404 | No such resource in this workspace |
| [`capability_not_ready`](https://docs.vlayers.ai/errors/capability_not_ready) | 409 | The sender cannot do this right now |
| [`recipient_opted_out`](https://docs.vlayers.ai/errors/recipient_opted_out) | 409 | The person opted out |
| [`idempotency_conflict`](https://docs.vlayers.ai/errors/idempotency_conflict) | 409 | The Idempotency-Key names a different message |
| [`window_closed`](https://docs.vlayers.ai/errors/window_closed) | 409 | The channel's reply window is closed |
| [`controller_conflict`](https://docs.vlayers.ai/errors/controller_conflict) | 409 | The conversation has another controller |
| [`controller_unsupported`](https://docs.vlayers.ai/errors/controller_unsupported) | 409 | This conversation cannot have that controller |
| [`channel_not_priced`](https://docs.vlayers.ai/errors/channel_not_priced) | 409 | The channel has no delivery price |
| [`channel_not_supported`](https://docs.vlayers.ai/errors/channel_not_supported) | 409 | This sender cannot send on that channel |
| [`not_linkable`](https://docs.vlayers.ai/errors/not_linkable) | 409 | The send cannot become a conversation message |
| [`number_inactive`](https://docs.vlayers.ai/errors/number_inactive) | 409 | The number is not active |
| [`plugin_suspended`](https://docs.vlayers.ai/errors/plugin_suspended) | 409 | The channel is suspended for this workspace |
| [`outcome_unknown`](https://docs.vlayers.ai/errors/outcome_unknown) | 409 | A provider attempt has no recorded result |
| [`send_in_progress`](https://docs.vlayers.ai/errors/send_in_progress) | 409 | A request with this Idempotency-Key is still in flight |
| [`content_too_long`](https://docs.vlayers.ai/errors/content_too_long) | 422 | The text is longer than the channel takes |
| [`media_too_large`](https://docs.vlayers.ai/errors/media_too_large) | 413 | The media is larger than the channel takes |
| [`media_unavailable`](https://docs.vlayers.ai/errors/media_unavailable) | 422 | The media could not be fetched or is not carried |
| [`operation_not_supported`](https://docs.vlayers.ai/errors/operation_not_supported) | 422 | The channel does not support this yet |
| [`output_refused`](https://docs.vlayers.ai/errors/output_refused) | 422 | The output guard refused the text |
| [`rate_limited`](https://docs.vlayers.ai/errors/rate_limited) | 429 | Too many requests |
| [`channel_not_registered`](https://docs.vlayers.ai/errors/channel_not_registered) | 503 | The channel is reloading |
| [`trust_unavailable`](https://docs.vlayers.ai/errors/trust_unavailable) | 503 | Message checks are briefly unavailable |
| [`wallet_unavailable`](https://docs.vlayers.ai/errors/wallet_unavailable) | 503 | The wallet is briefly unavailable |
| [`messaging_unavailable`](https://docs.vlayers.ai/errors/messaging_unavailable) | 503 | Sending is briefly unavailable |
| [`provider_error`](https://docs.vlayers.ai/errors/provider_error) | 502 | The provider did not take the message |
| [`provider_retry_later`](https://docs.vlayers.ai/errors/provider_retry_later) | 503 | The provider is rate limiting this sender |
| [`no_sender`](https://docs.vlayers.ai/errors/no_sender) | 409 | Nothing to send from on this channel |
| [`sender_ambiguous`](https://docs.vlayers.ai/errors/sender_ambiguous) | 409 | Several senders could send this |
| [`recipient_not_allowed`](https://docs.vlayers.ai/errors/recipient_not_allowed) | 403 | The channel does not allow this recipient |
| [`test_mode_only`](https://docs.vlayers.ai/errors/test_mode_only) | 403 | Only a test key can do this |
| [`test_address_required`](https://docs.vlayers.ai/errors/test_address_required) | 422 | A test key can only reach a test address |
| [`test_address_not_allowed`](https://docs.vlayers.ai/errors/test_address_not_allowed) | 422 | A live key cannot reach a test address |
| [`test_limit_reached`](https://docs.vlayers.ai/errors/test_limit_reached) | 429 | The workspace's test allowance for today is used |
| [`invalid_event_types`](https://docs.vlayers.ai/errors/invalid_event_types) | 400 | Unknown event types |
| [`invalid_conversation_id`](https://docs.vlayers.ai/errors/invalid_conversation_id) | 400 | The conversationId is not a conversation id |
| [`invalid_cursor`](https://docs.vlayers.ai/errors/invalid_cursor) | 400 | The cursor is not one this API returned |
| [`cursor_expired`](https://docs.vlayers.ai/errors/cursor_expired) | 410 | The cursor is older than the stream's replay window |
| [`events_unavailable`](https://docs.vlayers.ai/errors/events_unavailable) | 503 | Events are briefly unavailable |