Errors

ANT uses standard HTTP status codes and returns structured error responses.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "retryable": true | false
  }
}

code - Machine-readable error identifier
message - Human-readable description
retryable - Whether retrying might succeed

HTTP Status Codes

Status	Meaning	When It Occurs
`200`	OK	Request succeeded
`400`	Bad Request	Invalid request body, missing fields, invalid model
`401`	Unauthorized	Missing or invalid API key/session
`402`	Payment Required	Insufficient credits, or a budget cap reached (BUDGET_EXCEEDED)
`403`	Forbidden	Access denied, or a pinned model is not on the allowlist (MODEL_NOT_ALLOWED)
`429`	Rate Limited	Too many requests, retry after delay
`500`	Internal Error	Something went wrong on our end
`502`	Bad Gateway	Upstream provider returned an error
`503`	Service Unavailable	All providers failing, try again later

Error Codes

AUTH_FAILED

Authentication failed. The API key is invalid, revoked, or missing.

Fix: Check your API key is correct and not revoked.

INSUFFICIENT_CREDITS

Your workspace doesn't have enough credits for this request.

Fix: Top up your balance or add a provider API key (BYOK).

INVALID_REQUEST

The request body is malformed or missing required fields.

Fix: Check you're sending valid JSON with all required fields.

INVALID_MODEL

The requested model doesn't exist or isn't available.

Fix: Use a virtual model (ant:auto) or check the model name.

RATE_LIMITED

Too many requests in a short period.

Fix: Implement exponential backoff. Check Retry-After header.

PROVIDER_ERROR

The upstream LLM provider returned an error.

Fix: Usually transient. Retry or try a different model.

ALL_PROVIDERS_DOWN

All available providers are failing. Circuit breakers are open.

Fix: Wait and retry. If using BYOK, check your provider key is valid.

BUDGET_EXCEEDED

Returned with HTTP 402. A hard budget cap for the team or project has been reached for the current window (daily or monthly, UTC). Requests are rejected, not just warned.

Fix: Wait for the window to reset, or have an owner/admin raise the cap in billing/project settings.

MODEL_NOT_ALLOWED

Returned with HTTP 403. You pinned a specific model that is not on the team's (or project's) model allowlist.

Fix: Request an allowed model, use a virtual model like ant:auto (it routes within the allowed set), or add the model to the allowlist in settings.

INTERNAL_ERROR

An unexpected error occurred in ANT.

Fix: Retry. If persistent, contact support.

Retry Logic

Use exponential backoff for retryable errors:

async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (!error.retryable || i === maxRetries - 1) throw error;
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

Check the Retry-After header for rate limits — it tells you exactly how long to wait.