Skip to main content

Standard responses

Notation follows the APIs index.

APIs SHOULD NOT document standard responses because these responses apply to every API and documenting them over and over again just creates noise. The following responses are possible for every API:

ResponseDescription
400A malformed request, such as invalid JSON.
401The caller is not recognized, meaning not authenticated.
403The caller is not authorized to invoke the API.
404The resource specified via the URL path does not exist, or the caller is not allowed to know it exists.
405The HTTP method is not allowed.
406The API does not return the specified media type.
409The attempted update conflicts with some other update, because the resource changed since the caller last read it.
415The API does not accept the specified media type.
422An error the client can fix.
429The caller has made too many requests.
500An unexpected error the client cannot fix.
501The API has just been stubbed out and has not been implemented, yet.
503The service or a dependency is unavailable, overloaded, or timed out.

The status codes and their meanings are credited to RFC 9110 HTTP Semantics.

400 vs. 422​

  • Return 400 for requests that are malformed and cannot even be parsed, such as invalid JSON.
  • Return 422 for invalid requests. See Request validation.

403 vs. 404​

  • Return 403 for attempts to read, write, or act upon resources the user is allowed to know exist.
  • Return 404 for attempts to read, write, or act upon resources the user should not know exist.

404 vs. 422​

  • If the resource specified by the URL is not found, or the caller should not know it exists, APIs MUST return 404.
  • If the resource specified by the URL is found, but a resource referenced within the payload does not exist, or the caller should not know it exists, APIs MUST return 422.

500 vs. 503​

  • Return 500 for unexpected errors that occur within the service that the client cannot fix. By definition, a 500 is a bug.
  • Return 503 when the service is overloaded or a dependency is down, unreachable, or timed out.