What do the common HTTP status codes mean when you call a network API?
Show the answer
Say this first
2xx is success: 200 OK with a body, 201 Created, 204 No Content (success, no body). 4xx is the client's fault: 400 bad request body, 401 not authenticated, 403 authenticated but not allowed, 404 no such resource, 409 conflict such as the object already exists. 5xx is the server's fault: 500 internal error, 503 unavailable. My scripts retry 429 and 503 with backoff, re-authenticate on 401, and never blindly retry other 4xx.
Go deeper
The codes to know cold
| Code | Meaning | Typical network API cause |
|---|---|---|
| 200 OK | Success with a body | GET returned data |
| 201 Created | New resource made | POST or PUT created an object; Location header points to it |
| 204 No Content | Success, nothing to return | RESTCONF PUT, PATCH or DELETE that worked |
| 400 Bad Request | Malformed or invalid request | Bad JSON, wrong field name, missing module prefix, value out of range |
| 401 Unauthorized | Not authenticated | Missing, wrong or expired token or password |
| 403 Forbidden | Authenticated, not allowed | Read-only account tries a change; RBAC denies it |
| 404 Not Found | No such resource | Wrong URI, typo in the model path, object not configured |
| 405 Method Not Allowed | Method not supported here | PUT on a read-only resource |
| 409 Conflict | Clashes with current state | POST of an object that already exists; datastore locked |
| 415 Unsupported Media Type | Server cannot read the body format | Wrong Content-Type |
| 429 Too Many Requests | Rate limited | Too many calls; honor Retry-After |
| 500 Internal Server Error | Server failed | Bug or crash on the API side |
| 503 Service Unavailable | Temporarily down | Controller starting, overloaded or in maintenance |
The classes
1xx informational, 2xx success, 3xx redirect (301, 302, 304), 4xx client error, 5xx server error.
RESTCONF specifics (RFC 8040)
Errors come back with a body that holds error-type, error-tag and error-message. For example
data-exists and lock-denied both map to 409.
They will ask next
What is the real difference between 401 and 403?
401 means "I do not know who you are": the credentials are missing or bad, and retrying with valid ones can work. 403 means "I know who you are and the answer is no": new credentials for the same user will not help.
Your script gets 500 on one device and 200 on the rest. What do you do?
Log the full response body, because the server usually says what failed. Retry once in case it was transient. If it repeats, check the device's API process and logs; on IOS-XE,
show platform software yang-management processshows whether the programmability processes are running.
Traps
- Swapping 401 and 403.
- Treating every non-200 as failure. 201 and 204 are success.