Errors

Every error from the Mojeeb Public API uses the same envelope. Branch on code (stable, forever-additive) — never on message (human-readable, may be reworded without notice).

What does an error response look like?

{
  "error": {
    "type":           "validation_error",
    "code":           "invalid_from_phone",
    "message":        "The 'from' field must be an E.164 phone number...",
    "param":          "from",
    "correlation_id": "req_01KQ..."
  }
}

Field	Always present?	Purpose
type	Yes	Stable category for catch blocks
code	Yes	Stable, specific reason — branch on this
message	Yes	Human-readable; never use as a key
correlation_id	Yes	Trace id for our logs — quote in support tickets
Extra fields	Sometimes	Per-error context (e.g. param, available_phones, original_correlation_id)

What are the error types?

A small, stable set of categories. Forever-additive — new types may appear, none will be removed:

type	Typical HTTP
authentication_error	401
permission_error	403
validation_error	413, 422
idempotency_error	409 / 422
rate_limit_error	429
quota_error	402
conflict_error	409
not_found_error	404
internal_error	500, 503 (and 401 when the key couldn't be checked)

What's the full code catalog?

Codes are a stable enum. New codes appear without notice; nothing existing will be renamed or repurposed.

code	HTTP	Meaning
invalid_api_key	401	Missing, malformed, unknown, revoked or expired key. Fix your Authorization header.
insufficient_scope	403	Key lacks the required scope (response includes required_scope).
agent_not_authorized	403	Key is restricted to specific agents and this one isn't on its list.
shared_with_other_agents	403	The knowledge base, or a custom API tool's site login, is also used by agents the key can't act on, so the key can't change it.
feature_not_available	403	Your plan doesn't include this: custom API tools are on paid plans. Upgrade, or use the endpoints your plan has.
not_note_author	403	Only a note's author can edit or delete it; a key acts as the person who created it.
system_note_read_only	403	Notes Mojeeb records, such as lead status changes, can't be edited or deleted.
agent_id_required	403	A key limited to some agents called a WhatsApp endpoint without a valid agent_id.
agent_not_found	404	The agent isn't one of your organization's agents.
not_found	404	The conversation, contact, note, lead, lead field, knowledge base, connection, custom API tool or comment isn't the agent's (a deleted conversation is not found too), a conversation's message you asked for isn't one of its messages, or the connection whose templates you asked for isn't a WhatsApp number. On the usage history, your organization has no subscription.
message_not_found	404	GET /v1/whatsapp/messages/{id}: the id doesn't exist, belongs to another organization, or was sent through an agent outside the key's agent list.
endpoint_not_found	404	No /v1/ endpoint matches the method and path, including an id that isn't a UUID. Check for typos.
lead_capture_not_found	404	The agent has no Capture Lead tool, so it has no lead capture prompt to read or change. Contact Mojeeb support to have the tool added.
invalid_request_body	422	A field is missing, has the wrong type, breaks a limit or a format (such as a lead phone or contact mobile that isn't E.164), or a query parameter's value isn't valid (response includes param naming it).
invalid_request	422	A business rule refused the change (for example an unknown lead status or a reserved lead field key), the cursor isn't one the API returned, or a message list's after isn't a message of the conversation or was sent together with cursor (both with param: after). The message says which.
invalid_date_range	422	The analytics window is out of bounds: to is before from, a date is later than today in UTC, or the window is longer than the endpoint allows. The message says which.
no_settings	422	A settings or conversation update sent nothing to change.
messaging_window_closed	422	A reply in a conversation whose customer hasn't written in the last 24 hours: WhatsApp, Facebook and Instagram won't deliver it. Nothing was sent. On WhatsApp, send a template.
channel_not_supported	422	A reply in a conversation on a channel Mojeeb can't send on yet (TikTok). Nothing was sent.
comment_already_hidden	422	hideComment on a comment that is hidden already.
comment_not_hidden	422	unhideComment on a comment that isn't hidden.
platform_hide_failed	422	Facebook or Instagram refused to hide or show the comment, for example because it was deleted, or couldn't be reached. It can be temporary.
field_not_writable	422	An agent update sent a value for a field a key can't change: status (so a key can't delete an agent), ai_model, model_provider, avatar_url or language (response includes param naming it). Nothing was changed.
unknown_timezone	422	time_zone isn't an IANA time zone id in Region/City form, such as Africa/Cairo (UTC is Etc/UTC).
invalid_follow_up_platform	422	A follow-up channel isn't whatsapp, facebook or instagram.
invalid_follow_up_steps	422	More steps than allowed, a delay out of range, or two steps with the same delay.
assignee_not_allowed	422	The teammate can't open the agent (they aren't in your organization, or they're limited to other agents), so the lead or conversation can't be assigned to them. Pick someone with can_open_agent: true on the agent's members list.
system_field	422	A built-in lead field (built_in: true), the lead statuses included, can't be changed or deleted through the API.
lead_field_limit_reached	422	The agent already has as many custom lead fields as the API can add. Delete one it no longer needs first.
connection_inactive	409	The connection is disconnected (active: false), so its settings can't be changed and its templates can't be listed. Reconnect it in the dashboard first.
connection_needs_reconnection	409	Meta no longer accepts the WhatsApp number's access (it was revoked or expired, or the number left its WhatsApp Business Account), so its templates can't be read. Reconnect the number in the dashboard; retrying won't help.
field_key_taken	409	The agent already has a lead field with this key, built-in fields included. Nothing was created. A create retried after a lost response lands here too, so list the lead fields and carry on.
no_current_usage_period	409	No billing period of your subscription covers now, so Mojeeb treats it as not renewed and the AI doesn't reply until a period opens. It clears when the renewal lands; if it lasts, contact support with the correlation_id. GET /v1/organization/usage also answers it when your organization has no subscription at all.
usage_periods_overlap	409	More than one billing period of your subscription covers now, so Mojeeb can't tell which limits apply. Contact support with the correlation_id.
login_shared	409	The custom API login you sent differs from the site's saved one, or carries a secret, and other tools use it. Send change_shared_login: true to change it for all of them, or leave login out.
tool_not_tested	409	A custom API tool can be switched on only after a passing test of its current request. Test it, then switch it on.
request_body_too_large	413	The request body is larger than 1 MB.
invalid_agent_id	422	agent_id isn't a valid UUID (WhatsApp endpoints).
invalid_phone_number	422	to isn't a valid E.164 number (WhatsApp endpoints). A lead phone or contact mobile that isn't E.164 is invalid_request_body.
invalid_from_phone	422	from isn't a valid E.164 number.
from_phone_not_found_for_agent	422	from is well-formed but doesn't match any active WhatsApp connection on the agent (response includes available_phones).
template_header_media_url_invalid	422	template.header_media_url isn't an absolute HTTPS URL.
template_not_found	422	The connection has no template with that name, whatever its status (response includes available_templates). When Mojeeb can't read the templates from Meta, or the number has more templates than Mojeeb reads and this one isn't among them, this check is skipped and the send is accepted.
template_not_found_for_language	422	The template has no version in that language, whatever its status (response includes available_languages).
idempotency_key_in_progress	409	A request with this key is still running, or one with it that was refused or failed after claiming the key (for example a reply's messaging_window_closed) started less than 60 seconds ago, whatever the body. Retry after Retry-After, or send the corrected request with a new key.
idempotency_key_in_use_with_different_params	422	The key belongs to an earlier accepted request that differs from this one: another body, or another endpoint or conversation (the same text replied in another conversation counts as different). The response includes original_correlation_id.
idempotency_unknown_outcome	500	An internal fault in the idempotency check (not expected). Retry with the same key and body.
unknown_send_outcome	500	An internal fault mapping the send result (not expected). Look up the message before sending again.
rate_limit_exceeded	429	Per-key rate limit hit: the default one, or the lower one of the WhatsApp template list or of replies in a conversation. Back off and retry after Retry-After.
test_rate_limited	429	Your company ran too many custom API tool tests this minute (30, across its keys and the dashboard). Retry after Retry-After.
message_limit_exceeded	402	Reserved: the subscription's message limit. Not sent today.
access_unavailable	503	The access check couldn't run: the key's, or when assigning a lead or a conversation, the teammate's. Retry with backoff.
meta_unavailable	503	Meta didn't return what was asked, such as a WhatsApp number's templates (an outage, a timeout or Meta's own rate limit). Retry with backoff.
internal_server_error	500, 401	Our problem: retry with exponential backoff, and if it persists, send us the correlation_id. With 401 it means we couldn't check the key; retry, don't rotate it.

What HTTP statuses can the API return?

Status	Meaning
200	Success with a body (a read, an update or an assignment)
201	Resource created (a lead, a note, a knowledge base, a lead field, a custom API tool, a reply in a conversation)
202	Accepted for async processing (a message queued for send)
204	Success with no body (a delete)
401	Authentication failed
402	Reserved: quota exceeded
403	Authorization failed (scope, agent list, shared knowledge or login, note author, a feature your plan doesn't include)
404	Resource not found
409	Conflict (idempotency key in progress, a disconnected connection or one that needs reconnecting, a lead field key that already exists, no single current billing period, a shared custom API login, or an untested tool)
413	Request body larger than 1 MB
415	The body isn't sent as application/json (a standard problem-details body, not the envelope)
422	Validation error, including a body that isn't valid JSON
429	Rate limit exceeded
500	Internal error
503	The access check or Meta temporarily unavailable

Which errors should I retry?

Retry only the temporary ones. Wait for Retry-After on 429 and on 409 idempotency_key_in_progress. Use exponential backoff on 503 errors, on 500 errors except unknown_send_outcome, on 422 platform_hide_failed (Facebook or Instagram may just be unavailable), and on a 401 whose code is internal_server_error. Every other error needs a change before you send the request again.

Error	What to do
409 connection_inactive, 409 connection_needs_reconnection	Reconnect the connection in the dashboard, then try again.
409 field_key_taken	The field already exists: list the agent's lead fields and carry on.
409 no_current_usage_period	Wait: it clears when the renewal lands. Contact support if it lasts. With no subscription at all it won't clear until you subscribe.
409 usage_periods_overlap	Contact support with the correlation_id.
409 login_shared	Leave login out, or send change_shared_login: true if every tool on the site should change.
409 tool_not_tested	Test the tool, then switch it on in a request of its own.
500 unknown_send_outcome	Look up the message before sending it again.
422 messaging_window_closed	Wait for the customer to write, or, on WhatsApp, send a template.
422 platform_hide_failed	Try again later, with backoff. If it keeps failing, the comment was probably deleted.
422 comment_already_hidden, 422 comment_not_hidden	Nothing to fix: the comment is already as you asked. After a 500, it means your first request went through.
Any other 4xx	Fix the request; the code and message say what to change.

How do I use the correlation_id?

Save it on every error. When you contact support, paste the correlation_id from the failing response — we can trace the entire request lifecycle in our logs in seconds.

You can also send your own trace id and we'll honor it when it's valid:

curl ... -H "X-Correlation-ID: my-app-trace-abc123"

Up to 128 characters: letters, digits, _ and -. An id that breaks these rules is ignored without an error and we generate one instead, so take the id from the response header rather than assuming yours was kept. We reflect the id in X-Correlation-ID on the response and embed it in any error body. If you don't send one, we generate req_<26-char ULID>.

Common questions

Why does invalid_api_key cover so many sub-cases?

A single code keeps client logic simple — your code only needs one branch for "auth failed." The message field disambiguates for humans debugging, but you should never branch on text. Treat any invalid_api_key as "fix the key and retry."

Will you add new error codes later?

Yes. New code values can appear without notice as we add features. Keep your switch/match statements default-safe — fall back to "unknown error, log and surface to user."

What about field-level errors with multiple invalid fields?

Currently the API returns the first validation error encountered. We may add a richer multi-error shape later as an additive change (a new optional field on the envelope, never replacing existing fields). For now, fix one error at a time.

What's original_correlation_id?

Returned on idempotency_key_in_use_with_different_params. It points to the trace id of the request that originally claimed the idempotency key, so you can find that earlier request in your own application logs.

What's available_phones?

Returned on from_phone_not_found_for_agent. Lists every active WhatsApp number on the agent in E.164 format, so you can self-correct your from value without a second roundtrip to discover what was valid.