Use when designing new HTTP endpoints, reviewing endpoint designs for agent-friendliness, or verifying naming, error schema, pagination, and auth conventions
camelCase, verb+noun: createProject, listFiles, deleteUser, uploadProjectFile. Unique across the entire spec. Required on every endpoint — agents use these as function names. Never handler_post, api_v1_projects_post, or any auto-generated name.
| Code | Meaning | Agent action |
|---|---|---|
| 400 | Invalid request syntax | Fix the request — do not retry |
| 401 | Bad/expired credentials | Check code field: TOKEN_EXPIRED → refresh; TOKEN_INVALID → re-authenticate; do not retry the original request |
| 404 | Not found | Check IDs — do not retry |
| 409 | Conflict | Read conflicting_id from response to resolve without extra call — do not retry |
| 422 | Business logic validation | Fix configuration per detail — do not retry |
| 429 | Rate limited | Read Retry-After header (seconds); fall back to 60s if absent; retry |
| 500 | Server error | Retry only if method is safe or endpoint is idempotent (see retry matrix) |
| 502 | Upstream unavailable | Same as 500 |
| 410 | Gone (deliberately removed) | Do not retry; endpoint is permanently removed |
Use 422 (not 400) for business logic failures. 400 is for malformed requests; 422 is for well-formed requests that violate business rules.
| Method | Safe to retry? | Condition |
|---|---|---|
| GET, HEAD, OPTIONS | Always | Reads only — no side effects |
| DELETE | Always | Idempotent by definition |
| PUT | Always | Idempotent by definition |
| POST | Only if x-agent-retryable: true in spec, or Idempotency-Key was sent | Check the spec before retrying |
| POST (non-idempotent) | Never | Retrying creates duplicates |
After max retries (3): surface the error to the user with the request_id. Do not silently swallow.
Retry backoff: parse Retry-After header if present; otherwise use exponential backoff starting at 1s (1s, 2s, 4s).
x-agent-* OpenAPI extensionsAdd to every operation so agents can introspect behaviour from the spec itself: