The Complete HTTP Error Code Reference for Agent Readiness

Agent receives data and proceeds. The baseline for all agent interactions.

{ "data": { ... }, "meta": { "request_id": "req_abc123", "timestamp": "2026-04-15T10:00:00Z" } }

Agent confirms creation and stores the returned resource ID for future operations.

{ "data": { "id": "res_xyz789", "created_at": "..." }, "meta": { "request_id": "req_abc123" } }

Agent confirms success by status code alone. Used for DELETEs and updates where no data needs to return.

(empty body — agent reads status code)

Agent must follow Location header and update its stored URL. Failure to follow = broken integration.

Location: https://api.example.com/v2/resource
{ "error": "moved_permanently", "new_url": "https://api.example.com/v2/resource" }

Agent follows redirect but keeps original URL. Common in OAuth flows. Agents need to handle redirect chains.

Location: https://auth.example.com/callback
(Agent follows automatically)

Agent uses cached data. Saves bandwidth and latency. Agents that send If-None-Match headers get faster responses.

(empty body — agent uses cached version)

Agent re-sends the same request (including POST body) to the new Location. Critical for payment flows where method matters.

Location: https://api.example.com/v2/payments
(Agent re-sends with same method and body)

Agent needs specific field-level errors to self-correct. HTML error pages or generic "bad request" kill agent workflows.

{ "error": "validation_error", "code": "INVALID_INPUT", "message": "2 validation errors", "details": [{ "field": "email", "issue": "invalid format" }, { "field": "amount", "issue": "must be positive" }], "request_id": "req_abc123" }

Agent knows it needs to authenticate. Agent-ready response tells the agent HOW to authenticate (Bearer token, API key, OAuth flow URL).

{ "error": "unauthorized", "code": "AUTH_REQUIRED", "message": "Valid API key required", "auth_methods": ["bearer_token", "api_key"], "docs_url": "https://docs.example.com/auth", "request_id": "req_abc123" }

Agent is logged in but lacks permission. Must tell agent which permission is missing and how to request it.

{ "error": "forbidden", "code": "INSUFFICIENT_PERMISSIONS", "message": "Requires write:orders scope", "required_scope": "write:orders", "current_scopes": ["read:orders"], "upgrade_url": "https://app.example.com/settings/api", "request_id": "req_abc123" }

Agent needs to know if the resource never existed vs was deleted. Suggest alternative endpoints or search functionality.

{ "error": "not_found", "code": "RESOURCE_NOT_FOUND", "message": "Order ord_123 not found", "resource_type": "order", "suggestion": "Use GET /orders to list available orders", "request_id": "req_abc123" }

Agent used wrong verb. Response must include Allow header listing valid methods.

Allow: GET, POST
{ "error": "method_not_allowed", "code": "INVALID_METHOD", "message": "PATCH not supported. Use PUT for full updates.", "allowed_methods": ["GET", "POST", "PUT"], "request_id": "req_abc123" }

Agent tried to create a duplicate or update stale data. Must include the conflicting field and current state.

{ "error": "conflict", "code": "DUPLICATE_RESOURCE", "message": "Email already registered", "conflicting_field": "email", "existing_resource_id": "usr_456", "request_id": "req_abc123" }

Agent sent valid syntax but business logic rejected it. Needs specific business rule explanation.

{ "error": "unprocessable", "code": "BUSINESS_RULE_VIOLATION", "message": "Cannot schedule appointment in the past", "rule": "appointment_date must be > now()", "earliest_valid": "2026-04-16T09:00:00Z", "request_id": "req_abc123" }

Agent must wait and retry. Without Retry-After header, agent guesses and hammers your API. With it, agent waits precisely.

Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1713200000
{ "error": "rate_limited", "code": "RATE_LIMIT_EXCEEDED", "message": "100 requests per minute exceeded", "retry_after_seconds": 30, "request_id": "req_abc123" }

Agent cannot proceed. Must include request_id for debugging and suggest retry. Never expose stack traces.

{ "error": "internal_error", "code": "SERVER_ERROR", "message": "An unexpected error occurred", "request_id": "req_abc123", "retry": true, "retry_after_seconds": 5, "status_url": "https://status.example.com" }

Agent should retry after delay. Often transient. Include which upstream is down if possible.

{ "error": "bad_gateway", "code": "UPSTREAM_ERROR", "message": "Payment processor temporarily unavailable", "retry": true, "retry_after_seconds": 10, "status_url": "https://status.example.com", "request_id": "req_abc123" }

Agent waits for Retry-After and tries again. Without structured response, agent abandons the workflow.

Retry-After: 300
{ "error": "service_unavailable", "code": "MAINTENANCE", "message": "Scheduled maintenance until 2026-04-15T12:00:00Z", "retry": true, "retry_after_seconds": 300, "maintenance_end": "2026-04-15T12:00:00Z", "request_id": "req_abc123" }

Agent should retry with exponential backoff. Include whether the original request may have partially completed.

{ "error": "gateway_timeout", "code": "UPSTREAM_TIMEOUT", "message": "Request timed out after 30s", "retry": true, "retry_after_seconds": 15, "idempotent": true, "request_id": "req_abc123" }