AtlasFlux API error codes and retry behavior

Error response format

AtlasFlux returns errors as JSON. The type and error.code fields are intended for programmatic handling; messages and guidance are written for developers and may evolve.

{
  "type": "error",
  "error": {
    "message": "Your AtlasFlux balance is insufficient to complete this request.",
    "type": "billing_error",
    "code": "insufficient_balance",
    "param": null,
    "request_id": "req_abc123",
    "guidance": "Add credits to your AtlasFlux balance, then retry the request.",
    "action_url": "https://platform.atlasflux.my/dashboard/billing",
    "retryable": false
  }
}

retry_after_seconds is included when the API provides a specific retry interval, such as for rate limits. Always record request_id when reporting an issue to AtlasFlux support. Do not match on the full message string.

Error catalog

Authentication and access

Code	HTTP	Message	Guidance
`authentication_error`	401	AtlasFlux could not authenticate this request.	Check the Authorization header and make sure the AtlasFlux API key or session is valid.
`invalid_api_key`	401	The AtlasFlux API key is invalid.	Check the key and its status in the API Keys dashboard.
`expired_api_key`	401	This AtlasFlux API key has expired.	Create a new API key and update your application.
`revoked_api_key`	403	This AtlasFlux API key has been revoked.	Create a new API key and replace the revoked key.
`permission_denied`	403	This AtlasFlux API key is not allowed to perform this operation.	Check the key permissions and required access.

Billing

Code	HTTP	Message	Guidance
`insufficient_balance`	402	Your AtlasFlux balance is insufficient to complete this request.	Add credits at the Billing dashboard, then retry.
`spend_limit_exceeded`	402	The message identifies either the monthly limit or the per-request cost cap that would be exceeded.	Reduce request limits or adjust the applicable AtlasFlux spending limit.
`billing_error`	400	AtlasFlux billing could not complete this operation.	Review billing settings and try again later if needed.

Request and model validation

Code	HTTP	Message	Guidance
`invalid_request`	400	AtlasFlux identifies the invalid field or unsupported model in the message.	Review the request body, required fields, and parameter values.
`context_length_exceeded`	400	Your request exceeds the context limit for this AtlasFlux model.	Reduce conversation history, remove unnecessary content, or lower the requested output limit.
`unsupported_input`	400	AtlasFlux does not support one or more inputs in this request.	Review the endpoint/model documentation and remove or change the unsupported input.

When token counts are available, the context error includes the measured and maximum values:

Your request requires approximately 65,732 tokens, but this AtlasFlux model supports a maximum of 64,391 tokens.

An unsupported model is rejected before model execution and therefore is not charged. Generation endpoints return HTTP 400; GET /v1/models/{model} returns HTTP 404 when that catalog entry does not exist. Use GET /v1/models to discover accepted identifiers. When max_total_cost_myr is too low for the configured request, the error also reports the estimated maximum and requested cap, then identifies which output or search settings to reduce.

Rate limits

Code	HTTP	Message	Guidance
`rate_limit_exceeded`	429	AtlasFlux request rate limit exceeded.	Wait for the retry interval and use the `Retry-After` header when available.

Temporary processing errors

Code	HTTP	Message	Guidance
`provider_unavailable`	502/503	AtlasFlux is temporarily unable to process this request.	Retry with exponential backoff and include the request ID when contacting support.
`provider_timeout`	504	AtlasFlux timed out while processing this request.	Retry, reduce request size, or use streaming for longer responses.
`search_error`	502	AtlasFlux web search could not be completed.	Retry later or disable web search and submit the request again.

Conflicts and server errors

Code	HTTP	Message	Guidance
`idempotency_conflict`	409	This idempotency key was already used with a different request payload.	Use a new key or resend the original payload unchanged.
`not_implemented`	501	This AtlasFlux capability is not available yet.	Check the API documentation for supported capabilities.
`internal_error`	500	AtlasFlux could not complete the request due to an internal error.	Retry with exponential backoff and contact support with the request ID if it persists.

Retry behavior

Status	Retry	Action
400, 401, 403, 409	No	Fix the request, API key, permission, or idempotency key.
402	No	Add credits or adjust the applicable spending limit.
413	No	Reduce the request body.
429	Yes	Wait for `Retry-After` or `retry_after_seconds`, then retry.
502, 503, 504	Yes	Retry with exponential backoff.
500	Conditional	Retry only when `retryable` is `true`.

Core Concepts

Guides

API Reference

Resources

AtlasFlux API error codes and retry behavior

Error response format

Error catalog

Authentication and access

Billing

Request and model validation

Rate limits

Temporary processing errors

Conflicts and server errors

Retry behavior

​Error response format

​Error catalog

​Authentication and access

​Billing

​Request and model validation

​Rate limits

​Temporary processing errors

​Conflicts and server errors

​Retry behavior

Error response format

Error catalog

Authentication and access

Billing

Request and model validation

Rate limits

Temporary processing errors

Conflicts and server errors

Retry behavior