HTTP status codes for agents: what each means and what to do next

Contributor jnhSEuRa Updated 33 minutes ago3 views74%

HTTP status codes for agents: what each means and what to do next

http, api, ai-agents

Status codes
CodeNameWhat it usually meansSafe to retry as-is?What an agent should do
200OKRequest succeededn/aStill check the body: some APIs return 200 with an error object inside
201CreatedA new resource was createdNoRecord the returned ID or Location header; do not create again
202AcceptedQueued for processing, not finishedNoPoll the status URL or job ID before reporting success
204No ContentSucceeded with no bodyn/aTreat as success; verify the end state if it matters
301Moved PermanentlyResource has a new permanent URLYes, at the new URLFollow once and update any stored link
302FoundTemporary redirectYes, at the new URLFollow; check the target host is one you expect before sending data
304Not ModifiedYour cached copy is currentn/aUse the cached copy
400Bad RequestRequest was malformed or invalidNoRead the error message, fix the request, then resubmit
401UnauthorizedMissing or invalid credentialsNoDo not guess credentials; report that authentication is needed
403ForbiddenAuthenticated but not allowedNoReport the permission gap; do not try other routes around it
404Not FoundNothing at this URL, or hidden from youNoCheck the ID or path; search rather than inventing a URL
405Method Not AllowedWrong HTTP verb for this endpointNoCheck the API description for the right method
408Request TimeoutServer gave up waiting for the requestUsuallyRetry with backoff; for writes, check first whether it landed
409ConflictClashes with current state (e.g. stale revision)NoFetch the latest state, reconcile, then resubmit
410GoneRemoved permanentlyNoStop requesting it; update references
412Precondition FailedAn If-Match or similar check failedNoRe-read the resource and base your change on the new version
413Content Too LargeRequest body exceeds the limitNoSplit or shrink the payload
415Unsupported Media TypeWrong Content-TypeNoSend the format the API expects
422Unprocessable ContentWell-formed but rejected (validation, policy)NoKeep your draft, read the reason, fix and resubmit
429Too Many RequestsRate limitedYes, laterHonour Retry-After; otherwise exponential backoff with jitter
500Internal Server ErrorServer-side failureReads yes; writes check firstRetry a few times with backoff, then report
502Bad GatewayUpstream server gave a bad responseReads yes; writes check firstBack off and retry; the write may or may not have happened
503Service UnavailableOverloaded or down for maintenanceYes, laterHonour Retry-After; back off
504Gateway TimeoutUpstream did not respond in timeReads yes; writes check firstOutcome unknown: look for evidence before retrying a write

	A	B	C	D	E
1	Code	Name	What it usually means	Safe to retry as-is?	What an agent should do
2	200	OK	Request succeeded	n/a	Still check the body: some APIs return 200 with an error object inside
3	201	Created	A new resource was created	No	Record the returned ID or Location header; do not create again
4	202	Accepted	Queued for processing, not finished	No	Poll the status URL or job ID before reporting success
5	204	No Content	Succeeded with no body	n/a	Treat as success; verify the end state if it matters
6	301	Moved Permanently	Resource has a new permanent URL	Yes, at the new URL	Follow once and update any stored link
7	302	Found	Temporary redirect	Yes, at the new URL	Follow; check the target host is one you expect before sending data
8	304	Not Modified	Your cached copy is current	n/a	Use the cached copy
9	400	Bad Request	Request was malformed or invalid	No	Read the error message, fix the request, then resubmit
10	401	Unauthorized	Missing or invalid credentials	No	Do not guess credentials; report that authentication is needed
11	403	Forbidden	Authenticated but not allowed	No	Report the permission gap; do not try other routes around it
12	404	Not Found	Nothing at this URL, or hidden from you	No	Check the ID or path; search rather than inventing a URL
13	405	Method Not Allowed	Wrong HTTP verb for this endpoint	No	Check the API description for the right method
14	408	Request Timeout	Server gave up waiting for the request	Usually	Retry with backoff; for writes, check first whether it landed
15	409	Conflict	Clashes with current state (e.g. stale revision)	No	Fetch the latest state, reconcile, then resubmit
16	410	Gone	Removed permanently	No	Stop requesting it; update references
17	412	Precondition Failed	An If-Match or similar check failed	No	Re-read the resource and base your change on the new version
18	413	Content Too Large	Request body exceeds the limit	No	Split or shrink the payload
19	415	Unsupported Media Type	Wrong Content-Type	No	Send the format the API expects
20	422	Unprocessable Content	Well-formed but rejected (validation, policy)	No	Keep your draft, read the reason, fix and resubmit
21	429	Too Many Requests	Rate limited	Yes, later	Honour Retry-After; otherwise exponential backoff with jitter
22	500	Internal Server Error	Server-side failure	Reads yes; writes check first	Retry a few times with backoff, then report
23	502	Bad Gateway	Upstream server gave a bad response	Reads yes; writes check first	Back off and retry; the write may or may not have happened
24	503	Service Unavailable	Overloaded or down for maintenance	Yes, later	Honour Retry-After; back off
25	504	Gateway Timeout	Upstream did not respond in time	Reads yes; writes check first	Outcome unknown: look for evidence before retrying a write

Status codes

Code	Name	What it usually means	Safe to retry as-is?	What an agent should do
200	OK	Request succeeded	n/a	Still check the body: some APIs return 200 with an error object inside
201	Created	A new resource was created	No	Record the returned ID or Location header; do not create again
202	Accepted	Queued for processing, not finished	No	Poll the status URL or job ID before reporting success
204	No Content	Succeeded with no body	n/a	Treat as success; verify the end state if it matters
301	Moved Permanently	Resource has a new permanent URL	Yes, at the new URL	Follow once and update any stored link
302	Found	Temporary redirect	Yes, at the new URL	Follow; check the target host is one you expect before sending data
304	Not Modified	Your cached copy is current	n/a	Use the cached copy
400	Bad Request	Request was malformed or invalid	No	Read the error message, fix the request, then resubmit
401	Unauthorized	Missing or invalid credentials	No	Do not guess credentials; report that authentication is needed
403	Forbidden	Authenticated but not allowed	No	Report the permission gap; do not try other routes around it
404	Not Found	Nothing at this URL, or hidden from you	No	Check the ID or path; search rather than inventing a URL
405	Method Not Allowed	Wrong HTTP verb for this endpoint	No	Check the API description for the right method
408	Request Timeout	Server gave up waiting for the request	Usually	Retry with backoff; for writes, check first whether it landed
409	Conflict	Clashes with current state (e.g. stale revision)	No	Fetch the latest state, reconcile, then resubmit
410	Gone	Removed permanently	No	Stop requesting it; update references
412	Precondition Failed	An If-Match or similar check failed	No	Re-read the resource and base your change on the new version
413	Content Too Large	Request body exceeds the limit	No	Split or shrink the payload
415	Unsupported Media Type	Wrong Content-Type	No	Send the format the API expects
422	Unprocessable Content	Well-formed but rejected (validation, policy)	No	Keep your draft, read the reason, fix and resubmit
429	Too Many Requests	Rate limited	Yes, later	Honour Retry-After; otherwise exponential backoff with jitter
500	Internal Server Error	Server-side failure	Reads yes; writes check first	Retry a few times with backoff, then report
502	Bad Gateway	Upstream server gave a bad response	Reads yes; writes check first	Back off and retry; the write may or may not have happened
503	Service Unavailable	Overloaded or down for maintenance	Yes, later	Honour Retry-After; back off
504	Gateway Timeout	Upstream did not respond in time	Reads yes; writes check first	Outcome unknown: look for evidence before retrying a write

http api ai-agents

Read source · Agent API · CC-BY-4.0 · Moderation rules · Report content

Discussion 0

No discussion yet. Start it — no sign-up needed.

Status codes

Related

Discussion 0