API Reference · Basics

Errors

How the Inboxi API reports failures: the error envelope, HTTP status codes and the machine-readable error codes you can branch on.

When a request fails, Inboxi responds with a non-2xx HTTP status and success: false. Use the HTTP status for the broad category and, where present, the machine-readable code for the precise reason. Never parse the human-readable text: it can change.

Error envelope

Most errors carry a human-readable error string:

json

{
  "success": false,
  "error": "Required fields: source, dataType, data"
}

The event-messaging endpoints put a stable code in error and the explanation in message:

json

{
  "success": false,
  "error": "MISSING_FIELDS",
  "message": "Missing required fields: student_name, course_name"
}

Plan, module, authentication and credit errors add a code field next to error. The WhatsApp template endpoints describe the failure in message (the send endpoint sets both error and message). A robust client reads code first, then error, then message.

HTTP status codes

Status	Meaning	Typical cause
200	OK	The request succeeded.
201	Created	A webhook, remote action or external-data record was created.
202	Accepted	An event was accepted and queued (or scheduled) for sending.
400	Bad Request	A required field is missing or invalid, or the workspace has no active WhatsApp connection.
401	Unauthorized	Missing, invalid, inactive or expired API key or session token.
402	Payment Required	Out of AI credits (AI template generation).
403	Forbidden	The key lacks a permission, the plan does not include the feature, or the module is disabled.
404	Not Found	The record does not exist or belongs to another workspace.
422	Unprocessable	Template send attempted without a connected WhatsApp number.
429	Too Many Requests	Rate limit exceeded, or an event cooldown is active.
500	Server Error	Unexpected failure, including errors passed through from Meta. Retry with backoff; contact support if it persists.

Error codes

These are the codes the API returns today, and where they appear.

Code	Status	Returned by	What to do
`VALIDATION_ERROR`	400	POST /api/v1/events/trigger	Send both `event` and `phone`; `data` must be an object.
`EVENT_NOT_ACTIVE`	400	POST /api/v1/events/trigger	The event name does not exist or is switched off. Activate it in Settings › Automated Messages.
`MISSING_FIELDS`	400	POST /api/v1/events/trigger	Add the required variables listed in the message.
`SCHEDULING_NOT_ALLOWED`	400	POST /api/v1/events/trigger	The event is marked sensitive (for example a one-time code) and cannot be scheduled. Remove `sendAt`.
`COOLDOWN_ACTIVE`	429	POST /api/v1/events/trigger	The same event was sent to this number within its cooldown. Wait `retryAfter` seconds or poll the returned `logId`.
`NOT_FOUND`	404	GET /api/v1/events/messaging/:logId/status	The log id is wrong or belongs to another workspace.
`INTERNAL_ERROR`	500	Event-messaging endpoints	Retry with backoff.
`FEATURE_LOCKED`	403	Every /api/v1 endpoint	The workspace plan does not include the feature. See Plans & features map.
`TOKEN_EXPIRED`	401	Session-token endpoints	Get a new access token and retry.
`TOKEN_INVALID`	401	Session-token endpoints	The bearer token is malformed or was not issued by Inboxi.
`MODULE_DISABLED`	403	/api/chats/*	The Inbox module is turned off for this workspace.
`INSUFFICIENT_CREDITS`	402	POST /api/whatsapp/templates/ai-generate	Top up AI credits.

Authentication and permission errors

These come from the API-key check that runs before every /api/v1 endpoint:

Status	error
401	`API key required. Pass it in X-API-Key header.`
401	`Invalid or inactive API key`
401	`API key has expired`
403	`Missing permission: read`
429	`Rate limit exceeded. Max 60 requests per minute.`

A session-token endpoint with a stale token answers:

json

{
  "success": false,
  "error": "Access token expired",
  "code": "TOKEN_EXPIRED",
  "details": "AuthToken_Check_Failed"
}

Plan errors (FEATURE_LOCKED)

When the workspace plan does not include the feature an endpoint needs, the response tells you which plan unlocks it:

json

{
  "success": false,
  "error": "This feature requires the Growth plan. Upgrade to unlock.",
  "code": "FEATURE_LOCKED",
  "feature": "api_access",
  "currentTier": "starter",
  "requiredPlan": "Growth",
  "upgradeUrl": "/settings/plans"
}

If the subscription is suspended or expired, the same response carries "error": "Subscription inactive" and the status in currentTier.

Retrying safely

Retry on 429 (after Retry-After) and on 500 (with exponential backoff).
Do not retry 400, 401, 403 or 404 unchanged; fix the request, credentials or plan first.
Before re-triggering an event after a timeout, check its status with the logId you received, so the customer does not get the message twice.
External-data pushes with an externalId are upserts, so repeating them is safe.