API reference

Errors

Aonis uses standard HTTP status codes and structured JSON error responses.

Error response

Fields can vary by error. The API may include a request ID in the error message and/or response headers.

json · Conceptual error response

{
  "error": {
    "message": "...",
    "type": "...",
    "param": "",
    "code": "..."
  }
}

message: human-readable description.
type: error category returned by the API.
code: machine-readable identifier when available.
param: related parameter when available.

Status reference

HTTP	Scenario	Code	Recommended action
400	Malformed JSON	May be empty	Check the request body and JSON syntax.
401	Missing, invalid, or disabled API key	May be empty	Check the Authorization header and API key.
403	Available balance cannot cover the request	insufficient_user_quota	Add balance in the Aonis dashboard before retrying.
404	The request URL or API route does not exist	May be empty	Check the request URL and API route.
429	The active rate-limit window was exceeded	May be empty	Wait before retrying and reduce request frequency.
503	The requested model is not currently available	model_not_found	Check the model ID and model availability.

Error examples

400

Invalid Request

Malformed JSON syntax causes the request to be rejected.

json · 400 response

{
  "error": {
    "code": "",
    "message": "Invalid request: invalid JSON request body.",
    "type": "new_api_error"
  }
}

401

Authentication Error

Missing, invalid, and disabled API keys currently use HTTP 401.

json · 401 response

{
  "error": {
    "code": "",
    "message": "Invalid token.",
    "type": "new_api_error"
  }
}

Send a valid key using Authorization: Bearer YOUR_AONIS_API_KEY.

403

Insufficient Balance

The account does not have enough available balance to complete the request.

json · 403 response

{
  "error": {
    "message": "Insufficient balance.",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

Review billing or add balance in the dashboard before retrying.

404

Unknown Endpoint

This status is for an unknown route or URL, not model availability.

json · 404 response

{
  "error": {
    "message": "Invalid URL (GET /v1/unknown-endpoint)",
    "type": "invalid_request_error",
    "param": "",
    "code": ""
  }
}

429

Rate Limit Exceeded

Too many requests were sent within the active rate-limit window.

json · 429 response

{
  "error": {
    "code": "",
    "message": "Rate limit exceeded.",
    "type": "new_api_error"
  }
}

503

Model Unavailable

The requested model is not currently available to the request.

json · 503 response

{
  "error": {
    "code": "model_not_found",
    "message": "The requested model is currently unavailable.",
    "type": "new_api_error"
  }
}

Check the Models page for currently available models.

Request IDs

Error responses may contain a request identifier inside the error message and/or response headers. When contacting support, include the request ID when available.

When to retry

400Do not automatically retry without fixing the request.
401Do not retry until authentication is corrected.
403Do not retry until balance is available.
404Do not retry without correcting the endpoint.
429Retry after waiting; use exponential backoff.
503Verify availability before retrying. Temporary failures may be retried with backoff.