Errors

The error format, a status code table, and retry recommendations.

The AISAR API returns errors in Laravel's standard JSON format. Every error response includes at least a message field with a human-readable description.

Basic shape

{
  "message": "Not found"
}

Validation errors (422) additionally include an errors field — an object keyed by field name, whose value is an array of error messages for that field:

Validation error example

{
  "message": "The channel_id field is required.",
  "errors": {
    "channel_id": ["The channel_id field is required."]
  }
}

Status code table

Code	When it occurs
`200 OK`	Request succeeded (a read, or an action that doesn't create a resource, e.g. `POST /messages/send`).
`201 Created`	A resource was created, e.g. `POST /v1/api-tokens`.
`401 Unauthorized`	The Bearer token is missing, invalid, or has been revoked.
`403 Forbidden`	The token lacks the required permission (e.g. `conversation.create`), or the company's plan doesn't include the needed feature — in that case the body additionally carries `error: "feature_not_available"`, `feature` and `required_plan`.
`404 Not Found`	The resource was not found, or does not belong to the token's company (e.g. a `channel_id` from a different company).
`422 Unprocessable Entity`	Request body validation failed, or a business-rule constraint was violated (e.g. `is_group: true` on a channel that doesn't support groups).
`429 Too Many Requests`	The token's rate limit was exceeded (see the Authentication guide).
`5xx`	An internal server error. Not caused by your request's content.

Example: feature-gate error

If the company is not on the Business plan (the api feature), requests to endpoints that require it are rejected:

403 response — feature unavailable

{
  "message": "Feature not available on your plan.",
  "error": "feature_not_available",
  "feature": "api",
  "required_plan": "business"
}

Retry recommendations

401, 403, 404, 422 — do not retry unchanged: fix the underlying cause first (the token, permissions, request body, or resource id).
429 — retry after the retry_after seconds from the response body (or the Retry-After header); back off exponentially on repeated 429s.
5xx — a transient server-side issue, safe to retry with exponential backoff (e.g. 1s, 2s, 4s, 8s…). For operations that create an entity (e.g. sending a message), make sure the retry is idempotent on your side so it doesn't create a duplicate.