Errors

Error envelope

Every failed response uses the same envelope structure as a success, with status: false and data: null:

{
  "status": false,
  "message": "Human-readable explanation of what went wrong",
  "data": null
}

The message field is always a plain-English string you can log or surface to a developer.

HTTP status codes

Status	Category	Meaning
`200`	Success	Request succeeded.
`201`	Success	Resource created.
`400`	Client error	Request payload failed DTO validation. Check required fields and 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. Read the message carefully — it usually names the failing field:

{
  "status": false,
  "message": "name should not be empty",
  "data": null
}

`401` invalid key

{
  "status": false,
  "message": "Invalid API key",
  "data": null
}

Check that X-API-Key is present, the value is the full key secret (not the publicKey), and the key has not been revoked.

`403` scope denied

{
  "status": false,
  "message": "Insufficient scope",
  "data": null
}

Add the missing scope 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

{
  "status": false,
  "message": "Rate limit exceeded",
  "data": null
}

Implement exponential backoff and retry after the window resets. See Rate Limits.

Troubleshooting checklist

Log the full request URL, method, headers (redact the key value), and response body.
Check status and message in the response envelope.
For 401/403 — re-read Authentication and verify key scopes.
For 400 — compare your request body against the DTO fields in the endpoint’s documentation.
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` invalid key

`403` scope denied

`429` rate limited

Troubleshooting checklist

​Error envelope

​HTTP status codes

​Common error scenarios

​400 validation error

​401 invalid key

​403 scope denied

​429 rate limited

​Troubleshooting checklist

Error envelope

HTTP status codes

Common error scenarios

`400` validation error

`401` invalid key

`403` scope denied

`429` rate limited

Troubleshooting checklist