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.
403FORBIDDENThe authenticated user is not allowed to perform the request.Stop retrying; report the permission issue.
404NOT_FOUNDThe requested resource does not exist.Check the endpoint or URL.
429RATE_LIMIT_EXCEEDED or DAILY_SEARCH_LIMIT_EXCEEDEDThe request exceeded a minute limit or the account's daily beta allowance.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_UNAVAILABLE or SEARCH_PAUSEDAdmission is unavailable or public search is temporarily paused.Retry later; do not spin in a tight loop.

Rate limits

During the free public beta, search requires signup and an API key and costs nothing; no credit card is required. Public limits are:

  • Up to 50 admitted searches per account per UTC day, shared across its API keys.
  • 30 requests per minute per IP, applied globally before authentication.
  • 60 requests per minute per authenticated user/account for search traffic.
  • Service-wide capacity limits.

A search counts toward the daily allowance only after authentication, schema validation, and minute limits pass. It remains counted if later provider work fails. Invalid and minute-limited requests do not consume the daily allowance. Beta limits and availability may change, and Apira may temporarily pause or discontinue the service.

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; 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.