Errors
HTTP status codes, error envelopes, and debugging expectations for DevDocs APIs.
DevDocs APIs should make failures actionable. Error responses should tell callers what failed, whether the request can be retried, and which trace or audit identifier operators can use to investigate.
Error envelope
{
"error": {
"code": "release_not_ready",
"message": "The release cannot be promoted until preview checks pass.",
"request_id": "req_123",
"retryable": false
}
}Common status codes
| Status | Meaning |
|---|---|
200 | Request succeeded |
201 | Resource created |
204 | Resource deleted or no response body is needed |
400 | Request shape is invalid |
401 | Authentication is missing or invalid |
403 | Caller lacks permission |
404 | Resource does not exist or is not visible to the caller |
409 | Resource state conflicts with the requested action |
422 | Request is syntactically valid but cannot be applied |
429 | Rate limit exceeded |
500 | Unexpected server error |
502 | Upstream execution failed |
504 | Upstream execution timed out |
Playground errors
The OpenAPI playground should distinguish:
- validation errors before a request is sent
- auth errors returned by the target API
- CORS or proxy eligibility errors
- network timeouts
- non-JSON responses
- server errors from the documented API
Good error handling is part of playground fluency. A developer should know whether to edit a parameter, change credentials, pick a different environment, or retry later.