Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Errors and Rate Limits

Apira returns structured JSON errors so agents can decide whether to revise the request, retry later, or stop and ask for operator action.

Error envelope

Errors use this shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "query is required",
    "status": 400
  }
}

Validation errors may also include a details array with field-level information.

Common status codes

StatusCodeMeaningAgent behavior
400VALIDATION_ERRORRequest body or parameters failed validation.Revise the tool arguments before retrying.
401AUTH_ERRORThe API key is missing or invalid.Stop and ask the operator to configure a valid key.
403FORBIDDEN or INSUFFICIENT_CREDITSThe authenticated user is not allowed to perform the request, or the account has no available credits.Stop retrying; report the permission or credit issue.
404NOT_FOUNDThe requested resource does not exist.Check the endpoint or URL.
429RATE_LIMIT_EXCEEDEDThe request exceeded a configured rate limit.Back off until Retry-After; preserve task state.
500INTERNAL_ERRORAn unexpected server error occurred.Retry with jitter if the user task can wait, otherwise degrade gracefully.
502EXTERNAL_SERVICE_ERRORAn upstream service failed.Retry with jitter or explain the upstream failure.
503RATE_LIMIT_UNAVAILABLEThe rate-limit backend is temporarily unavailable when configured to fail closed.Retry later; do not spin in a tight loop.

Rate limits

Default public limits are:

  • 30 requests per minute per IP, applied globally before authentication.
  • 60 requests per minute per authenticated user/account for search traffic.

Authenticated search requests can therefore be constrained by both the global per-IP limit and the authenticated user/account limit.

429 RATE_LIMIT_EXCEEDED responses include:

  • X-RateLimit-Limit: the limit for the current window.
  • X-RateLimit-Remaining: remaining requests in the current window.
  • X-RateLimit-Reset: Unix timestamp when the current window resets.
  • Retry-After: seconds to wait before retrying.

503 RATE_LIMIT_UNAVAILABLE responses are limiter-backend failures and may include only Retry-After.

Agent retry guidance

Agents should retry only when the error is likely transient:

  • Retry 429, 500, 502, and 503 with backoff and a maximum attempt count.
  • Do not retry 400 without changing the request.
  • Do not retry 401 or 403 INSUFFICIENT_CREDITS; these need operator or account action.
  • Preserve the user's task state so the agent can resume after waiting.
  • Disclose degraded results if the agent falls back to a broader search, cached candidates, or no Apira call.

For exact status codes and schemas, use the OpenAPI JSON.