Errors

Error envelope

A failed response uses a different shape from a success response — don’t reuse your success-parsing code for errors:

{
  "success": false,
  "error": {
    "code": "workflow_deprecated",
    "message": "Human-readable explanation of what went wrong",
    "reason": "Same as message, unless the server sets a more specific reason"
  },
  "meta": {
    "requestId": "f3c9b29a-9f4d-4b71-8b3b-2cb77f4e9cf1",
    "timestamp": "2026-06-02T10:30:45.123Z",
    "version": "v1"
  }
}

Field	Type	Description
`success`	boolean	Always `false` on an error response.
`error.code`	string	A short machine-readable code (e.g. `workflow_deprecated`), or the HTTP status name (e.g. `Forbidden`) when the server didn’t set an explicit code.
`error.message`	string \| string[]	Human-readable explanation. For `400` validation errors this is often an array of one message per failing field, not a single string.
`error.reason`	string	Usually identical to `message`; occasionally more specific.
`meta.requestId`	string	Correlates this response to a request; include it when contacting support.

HTTP status codes

Status	Category	Meaning
`200`	Success	Request succeeded.
`201`	Success	Resource created.
`400`	Client error	Request body failed validation. Check that required fields are present and have the expected types.
`401`	Auth error	`X-API-Key` header is missing, malformed, expired, or the key has been revoked.
`403`	Scope error	Key is valid but lacks the required scope for this endpoint. Add the scope via `PATCH /v1/auth/keys/{id}/scopes`.
`404`	Not found	The requested resource ID does not exist or does not belong to your organization.
`429`	Rate limited	Request rate exceeded `rateLimitPerMinute` or `rateLimitPerHour` for the key. Back off and retry.
`500`	Server error	Unexpected server-side failure. If it persists, contact support with the endpoint path and timestamp.

Common error scenarios

`400` validation error

Happens when required fields are missing or a field type is wrong. error.message is an array — one entry per failing field:

{
  "success": false,
  "error": {
    "code": "Bad Request",
    "message": ["name should not be empty"],
    "reason": ["name should not be empty"]
  },
  "meta": { "requestId": "...", "timestamp": "...", "version": "v1" }
}

`401` missing key

{
  "success": false,
  "error": {
    "code": "Unauthorized",
    "message": "Missing X-API-Key header",
    "reason": "Missing X-API-Key header"
  },
  "meta": { "requestId": "...", "timestamp": "...", "version": "v1" }
}

Check that the X-API-Key header is actually present on the request.

`404` invalid or expired key

An unrecognized or revoked key value returns 404, not 401:

{
  "success": false,
  "error": {
    "code": "Not Found",
    "message": "Invalid API key",
    "reason": "Invalid API key"
  },
  "meta": { "requestId": "...", "timestamp": "...", "version": "v1" }
}

A key past its expiresAt returns 400 with "message": "API key has expired" instead. In all three cases, check that X-API-Key is present, the value is the full key secret (not the publicKey), and the key hasn’t been revoked or expired.

`403` scope denied

{
  "success": false,
  "error": {
    "code": "Forbidden",
    "message": "Missing required scope: calls:write",
    "reason": "Missing required scope: calls:write"
  },
  "meta": { "requestId": "...", "timestamp": "...", "version": "v1" }
}

message always names the specific missing scope. Add it to your key:

curl -X PATCH https://api.indigenius.ai/v1/auth/keys/KEY_ID/scopes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["calls:read", "calls:write"]}'

`429` rate limited

{
  "success": false,
  "error": {
    "code": "Too Many Requests",
    "message": "Rate limit exceeded",
    "reason": "Rate limit exceeded"
  },
  "meta": { "requestId": "...", "timestamp": "...", "version": "v1" }
}

Implement exponential backoff and retry after the window resets. See Rate Limits — note that the enforced limit is currently a fixed platform-wide threshold, not the rateLimitPerMinute/rateLimitPerHour values you can set on a key.

Troubleshooting checklist

Log the full request URL, method, headers (redact the key value), and response body.
Check success and error.message in the response envelope.
For 401/404/403 — re-read Authentication and verify key scopes.
For 400 — compare your request body against the request body table in the endpoint’s documentation; remember error.message may be an array.
For 500 — retry once. If the error persists, contact support with the endpoint, payload, and a timestamp.

Getting Started

Core APIs

Platform APIs

Error envelope

HTTP status codes

Common error scenarios

`400` validation error

`401` missing key

`404` invalid or expired key

`403` scope denied

`429` rate limited

Troubleshooting checklist

​Error envelope

​HTTP status codes

​Common error scenarios

​400 validation error

​401 missing key

​404 invalid or expired key

​403 scope denied

​429 rate limited

​Troubleshooting checklist

Error envelope

HTTP status codes

Common error scenarios

`400` validation error

`401` missing key

`404` invalid or expired key

`403` scope denied

`429` rate limited

Troubleshooting checklist