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 may make the best effort to help customers with possible next steps in case of an error by adding a 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.

Validation Errors​

Validation errors occur when the client sends a request that does not meet the API's requirements. Proper validation is critical for maintaining data integrity and providing clear feedback to clients.

Validation errors typically occur when:

  • Required fields are missing

  • Data types don't match expected formats

  • Values fall outside acceptable ranges

  • Business rules are violated

  • APIs must return a 400 Bad Request status code when validation fails

  • APIs must not accept invalid requests and silently modify field values to make them valid

    • This violates the principle that client-owned fields must not be modified by the server (see IPA-111)

  • 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

Rate Limiting​

  • APIs must document the 429 Too Many Requests status code for endpoints that implement rate limiting.
  • APIs must return 429 Too Many Requests when a client exceeds the allowed request rate.
  • APIs should include the Retry-After HTTP response header when returning 429 Too Many Requests to indicate how long the client should wait before retrying the request.
    • The Retry-After header value must be expressed as time in seconds until the next request can be made.
  • APIs should include rate limit information in response headers to help clients manage their request rates proactively:
    • RateLimit-Limit: The maximum number of requests allowed in the current rate limit window
    • RateLimit-Remaining: The number of requests remaining in the current rate limit window

:::

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