Developer ToolsFree referencePDF, Excel, Word export

HTTP Status Codes for ERP API Calls: Retry or Stop Reference

When an AI agent or integration calls an ERP API, the status code decides whether it should retry, fix its request or stop and ask a human. This table lists the codes you meet in practice and what they usually mean on ERP REST and OData endpoints.

Download:

Status	Name	Class	Typical meaning on an ERP API	Safe to retry automatically?	What the agent or integration should do
200	OK	2xx success	Read or update succeeded and a body is returned	Not needed	Parse the body and continue
201	Created	2xx success	A new record such as an order or item was created	No, a retry may create a duplicate	Store the returned key or Location header
202	Accepted	2xx success	Request queued for asynchronous processing	No	Poll the status URL or wait for the callback
204	No Content	2xx success	Update or delete succeeded with no body	Not needed	Treat as success, re-read if the new state is needed
301	Moved Permanently	3xx redirect	Endpoint moved, often http to https or a tenant migration	Yes, at the new URL	Update the configured base URL
304	Not Modified	3xx redirect	Conditional GET with ETag found no change	Not needed	Use the cached copy
400	Bad Request	4xx client	Malformed JSON, bad filter syntax or invalid field value	No	Fix the payload or query, do not resend unchanged
401	Unauthorized	4xx client	Token missing, expired or invalid	Once, after refreshing the token	Refresh credentials, then retry one time
403	Forbidden	4xx client	Authenticated but the ERP role or scope lacks permission	No	Stop and request the right role, never loop
404	Not Found	4xx client	Wrong URL, wrong company or tenant, or record does not exist	No	Verify the key and company context
405	Method Not Allowed	4xx client	Entity set is read only or the verb is not exposed	No	Check the API documentation for allowed verbs
408	Request Timeout	4xx client	Server gave up waiting for the request	Yes for reads	Retry with backoff
409	Conflict	4xx client	Duplicate key, locked record or state conflict	No, re-read first	Fetch current state, decide, then resubmit
410	Gone	4xx client	Endpoint or API version retired	No	Migrate to the supported API version
412	Precondition Failed	4xx client	If-Match ETag no longer matches, record changed by someone else	No, re-read first	Reload the record and reapply the change
413	Payload Too Large	4xx client	Batch or attachment exceeds the gateway limit	No	Split into smaller batches
415	Unsupported Media Type	4xx client	Missing or wrong Content-Type header	No	Send application/json or the type the API requires
422	Unprocessable Content	4xx client	Syntax valid but a business rule failed, such as a closed period	No	Read the error body, correct the data
423	Locked	4xx client	Record locked by another user or process	Yes, a few times	Retry with backoff, then escalate
428	Precondition Required	4xx client	API requires If-Match for updates	No	Read the record, send its ETag
429	Too Many Requests	4xx client	Rate limit or API capacity reached	Yes, after the wait	Honor Retry-After, lower concurrency
500	Internal Server Error	5xx server	Unhandled error in the ERP service or a customization	Yes for reads, careful for writes	Retry with backoff, log the correlation ID
501	Not Implemented	5xx server	Operation not supported by this ERP version	No	Use a different endpoint
502	Bad Gateway	5xx server	Gateway could not reach the ERP application server	Yes	Retry with backoff
503	Service Unavailable	5xx server	Maintenance window, restart or overload	Yes, after Retry-After if sent	Back off, pause the agent queue
504	Gateway Timeout	5xx server	Query ran longer than the gateway allows	Reads only, with a smaller query	Narrow filters or page the request

Retry guidance is general practice. Write calls should only be retried when the endpoint supports an idempotency key or when you confirmed the first attempt did not commit. Individual ERPs may use these codes slightly differently.

Error handling review for your ERP agent

Optional: send us your integration flow and we will mark where retries could duplicate data.

Optional. The tool and every export work without this. No spam.

How to use the table

Search by code or by a word from the error message. Read the ERP meaning first, because the same code can mean different things in different systems. Then check the retry column before writing any retry loop. The last column gives the behavior we recommend for an agent: stop, refresh, back off or re-read. Export the table to Excel to paste it into your integration design document or into the error-handling section of an agent runbook.

Retry rules that prevent damage

Retrying is safe when repeating the call has no extra effect. GET requests are safe. POST that creates a record is not safe unless the API supports an idempotency key. Never loop on 401 or 403, because repeating a denied call only fills the audit log and may lock the service account. For 429 and 503, honor the Retry-After header when present and reduce concurrency instead of only waiting.

Cap retries, three to five attempts is typical
Use exponential backoff with random jitter
Retry only idempotent calls unless a key is supported
Log the correlation or request ID from the response
Escalate to a person after the cap is reached

Conflict codes are not errors to hide

409, 412 and 423 tell you the ERP state changed or is held by someone else. An agent that blindly resends can overwrite a planner's change. The correct response is to re-read the record, compare, and either reapply the change deliberately or hand the decision to a person. 422 usually carries a business rule message such as a closed posting period; surface that message to the user instead of rewording the payload at random.

Common mistakes

Teams often treat every 5xx as retryable, including a timeout on a write that actually committed, which creates duplicate orders. Others treat 404 as a network issue when the real cause is a wrong company or tenant in the URL. Finally, many agents discard the response body on error, throwing away the ERP message that explains the fix. Always keep the body in the log.

Frequently Asked Questions

Should an AI agent retry a 500 error?

For a read, yes, with backoff and a retry cap. For a write, only after confirming the first attempt did not commit or when the endpoint supports an idempotency key. A 500 can occur after the ERP already saved the record, so blind retries can duplicate it.

What is the difference between 401 and 403 in an ERP API?

401 means the caller is not authenticated, usually an expired or missing token, so refreshing the token once is reasonable. 403 means the caller is known but the ERP role or scope does not allow the action, so retrying cannot help and a role change is needed.

Why do I get 429 from my ERP API?

You exceeded a rate or capacity limit, often a per-user or per-tenant request quota. Wait for the Retry-After period if given, reduce parallel calls, batch requests and cache reference data so the agent stops polling for unchanged records.

Is 409 Conflict the same as a duplicate record?

Often, but not always. It can also mean a locked record or a state conflict such as updating a closed order. Read the response body, re-read the current record, and decide whether to update, skip or ask a person.

Netray builds agents that read and, with approval, write back to ERPs with sensible retry and escalation rules. If you want error handling designed for your ERP, we can review your integration.

Talk to an Expert Explore More Free Tools

Related Tools

Developer Tools

More Developer Tools tools

See all

Back to All Tools