Skip to main content

IPA-114: Errors

Effective error communication is an important part of designing simple and intuitive APIs. Services returning standardized error responses enable API clients to construct centralized common error-handling logic. This common logic simplifies API client applications and eliminates the need for cumbersome custom error-handling code.

State

Adopt

Guidance​

  • APIs must return ApiError when errors occur
  • APIs should avoid unexpected errors (5XX) by correctly handling validations and exposing the appropriate error user error (4XX)
  • Errors must use the canonical error codes allowed for the errorCode field
  • APIs should make the best effort to validate as much as possible of the request and include all validation errors in the field badRequestDetail
    • badRequestDetail must include an array of fields and each field must include:
      • the error description as description
      • field with errors as field
  • APIs should make the best effort to help customers with possible next steps in case of an error by adding the help field
    • help must include a short description as description
    • help must include a link to the documentation url
  • Methods must document any possible error and their associated HTTP status code

Authentication and Authorization​

  • APIs must document 401 Unauthorized and 403 Forbidden status codes for endpoints that require authentication.
  • APIs must return 401 Unauthorized if the client lacks valid credentials.
  • APIs must return 403 Forbidden if the client is authenticated but does not have permission to access the resource.

Not Found​

  • APIs must document the 404 Not Found status code when the resource identifier includes one or more resource IDs.
  • APIs must return a 404 Not Found status code if the client provides an invalid or non-existent ID
tip

For path parameters consider applying regex-based routing to ensure invalid IDs are treated as 404 Not Found rather than 400 Bad Request.

API Error Format​

{
  "error": 400, // HTTP status code (required)
  "reason": "Bad Request", // Human-readable error message (optional)
  "detail": "The request content produced validation errors.", // Detailed description (optional)
  "errorCode": "BAD_REQUEST", // Application-specific error code (optional)
  "parameters": [], // Array of additional parameters (optional)
  "badRequestDetail": {
    // Only present for validation errors (optional)
    "fields": [
      {
        "field": "Request body", // Path to the problematic field
        "description": "must not be null" // Description of the violation
      }
    ]
  }
}

Example

{
  "badRequestDetail": {
    "fields": [
      {
        "description": "must not be null",
        "field": "groupId"
      },
      {
        "description": "must not be empty",
        "field": "authors[0].name"
      }
    ]
  },
  "detail": "The request content produced validation errors.",
  "error": 400,
  "errorCode": "BAD_REQUEST",
  "help": {
    "description": "troubleshooting documentation",
    "url": "https://www.mongodb.com/docs/atlas/reference/api-errors/"
  },
  "parameters": [],
  "reason": "Bad Request"
}
tip

New fields badRequestDetail and help are inspired by googleapis/google/rpc/error_details.proto