Errors

The Ayliea API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error format

All error responses return a JSON object with a single error field containing a human-readable message:

{
  "error": "Human-readable error description"
}

Error messages are intentionally general and do not expose internal implementation details.

Status codes

Code	Meaning	When it happens
`200`	OK	Request succeeded
`400`	Bad request	Invalid query parameters (e.g., `limit` out of range)
`401`	Unauthorized	Missing or invalid `X-API-Key` header
`403`	Forbidden	API key lacks the required scope, or API access is not included in your engagement
`404`	Not found	Requested resource does not exist
`409`	Conflict	Duplicate resource (e.g., maximum API keys reached)
`429`	Too many requests	Rate limit exceeded
`500`	Internal server error	Unexpected server-side failure

Example error responses

401 Unauthorized
403 Forbidden
400 Bad request
429 Rate limited
500 Server error

{
  "error": "Invalid API key"
}

{
  "error": "API key does not have the 'scores:read' scope"
}

{
  "error": "limit must be an integer between 1 and 100"
}

{
  "error": "Too many requests. Please try again later."
}

{
  "error": "Failed to query scores"
}

Handling errors

4xx errors indicate a problem with your request. Check the error message, fix the issue, and retry. 429 errors mean you have been rate limited. Wait for the Retry-After period and retry. See Rate limiting for details. 500 errors indicate a server-side problem. These are safe to retry with exponential backoff. If 500 errors persist, contact support@ayliea.com.

API Reference

Endpoints

Error format

Status codes

Example error responses

Handling errors

​Error format

​Status codes

​Example error responses

​Handling errors

Error format

Status codes

Example error responses

Handling errors