API error handling
Errors, rate limits, auth, fallback
In short: Next to your API docs, cover error codes, rate limits, authentication and how to recover (retries, backoff or a status page), each with specifics.
What it checks
Whether the API documentation covers errors, rate limits, auth and fallbacks.
Why it matters
An agent calling your API needs to know what to do when a call fails, how fast it may call, how to authenticate, and what to tell the user if it can’t.
When it applies
Applies when the file documents an API, OpenAPI spec, MCP server or WebMCP tools (the same signal as Machine surface). Otherwise Not applicable, with the whole endpoint block.
An audit that doesn't apply, or that we couldn't verify, is removed from your score and its weight shared among the Agent Readiness audits that do apply. It is never scored as a zero.
How it's scored
Each of four parts found is worth 0.25. Errors: an error format or status-code meaning (404 means …, problem+json). Rate limits: a 429, a Retry-After or RateLimit header, or a rate (“60 requests per minute”). Auth: how to authenticate (an API key, bearer token or OAuth) or that none is needed. Recovery: retries with their trigger, backoff, an idempotency key, or a link to a status page. A heading or link title counts when it names the part and the API (a heading needs a link, code or a value under it); prose counts only with a specific value next to the term, so a list of topic words (“errors, limits, auth, retries”) scores 0.
How to fix
- List the error codes an agent will meet, and what each means.
- State rate limits (a number and period, or the 429 and Retry-After behaviour) and how to back off.
- Explain authentication: the scheme, where the key goes, and what to do if the agent has no credentials.
- Say how to recover when a call fails: which errors to retry, and the status page or contact to use when the API is unavailable.
Example
## API
- Base URL: https://api.acme.com/v1
- [OpenAPI spec](https://api.acme.com/openapi.json): Full machine-readable reference
### Errors and limits
- Errors: the API returns problem+json; 404 means the resource does not exist and 422 means a parameter failed validation.
- Rate limits: 100 requests per minute; on 429, wait for the Retry-After header before retrying.
- Authentication: send your API key as a bearer token in the Authorization header.
- Recovery: retry a 503 with exponential backoff, and check https://status.acme.com when the API is unavailable.Frequently asked questions
What should llms.txt say about API errors, rate limits and auth?
Sources: LLMSRank — API error handling audit · RFC 6585 §4 — 429 Too Many Requests
How is the API error handling check measured today?
Sources: LLMSRank — API error handling audit · LLMSRank — How scoring works
Which standards should my documented API errors follow?
application/problem+json with type, title, status, detail and instance) for machine-readable error bodies, and RFC 6585’s 429 Too Many Requests, which may carry a Retry-After header saying how long to wait. An OpenAPI spec can document each error response by status code and your auth under securitySchemes.Sources: RFC 9457 — Problem Details for HTTP APIs · RFC 6585 §4 — 429 Too Many Requests · OpenAPI Specification (latest)
When is the API error handling check Not applicable?
Sources: LLMSRank — How scoring works · LLMSRank — API error handling audit
In our research, how often did API error handling apply?
Sources: LLMSRank — How scoring works · LLMSRank — API error handling audit