13. HTTP Status Codes and Errors

HTTP status codes are an essential part of REST API design. They communicate the outcome of a request and allow API consumers to correctly handle successful responses, client errors, and server errors.

APIs should use standard HTTP semantics consistently and avoid exposing implementation-specific details.

Define Success and Error Responses

API specifications must define both successful responses and service-specific error responses.

Success and error responses are part of the API contract. They describe how clients should interact with the API and how they should handle exceptional situations.

However, APIs should avoid documenting every possible technical error, especially errors caused by infrastructure components outside the service's control.

Instead, APIs should focus on:

• Business-relevant errors
• Errors that clients can handle differently
• Errors that require additional explanation beyond the HTTP status code

Example:

openapi: 3.0.3

paths:
  /resources:
    get:
      responses:
        default:
          description: Error occurred. See status code and problem details for more information.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

components:
  schemas:
    ProblemDetails:
      description: Provides additional information about an error response.
      type: object
      properties:
        type:
          type: string
          description: URI identifying the problem type.
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          description: URI identifying the specific occurrence of the problem.

Use Standard HTTP Status Codes

APIs must use standardized HTTP status codes according to their defined semantics.

Custom HTTP status codes must not be created.

Using standard status codes improves interoperability and avoids ambiguity for API consumers.

Success Status Codes

Redirection Status Codes

Client Error Status Codes

Client errors indicate that the request cannot be completed because of invalid input, authentication, authorization, or request conflicts.

Server Error Status Codes

Server errors indicate that the service failed while processing a valid request.

Use the Most Specific HTTP Status Code

APIs should always return the most specific HTTP status code that accurately describes the request outcome.

Avoid using generic codes such as 400 or 500 when a more specific status code exists.

Examples:

Incorrect:

POST /users

Response:
400 Bad Request

when the actual reason is:

409 Conflict

because the user already exists.

Correct:

HTTP/1.1 409 Conflict

Batch and Bulk Request Responses

Batch and bulk operations may contain multiple independent operations.

Because a single HTTP response code cannot represent multiple results, APIs should use:

207 Multi-Status

when individual operations produce different outcomes.

Rules:

• A batch or bulk request should return 207 when individual operation results need to be reported.
• The response body must contain status information for each individual operation.
• 4xx or 5xx responses should only be returned when the request fails before individual processing begins or when an unexpected global failure occurs.

Example:

{
  "results": [
    {
      "id": "123",
      "status": 200
    },
    {
      "id": "456",
      "status": 404,
      "detail": "Resource not found"
    }
  ]
}

Use Problem JSON Object

APIs should use the RFC 7807 Problem Details format for error responses.

Media type:

application/problem+json

Problem responses provide additional information beyond the HTTP status code.

Example:

components:

  schemas:

    Problem:
      description: Additional information about an API error.
      type: object

      properties:

        type:
          type: string

        title:
          type: string

        status:
          type: integer

        detail:
          type: string

        instance:
          type: string

Example response:

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "/problems/service-unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "The dependent service is temporarily unavailable.",
  "instance": "/requests/abc123"
}

Do Not Expose Stack Traces

APIs must never expose stack traces in responses.

Stack traces:

• Reveal internal implementation details
• May expose sensitive information
• Create security risks
• Encourage clients to depend on implementation behavior

Instead, return:

• Standard HTTP status codes
• Problem JSON objects
• Client-safe error descriptions

Example:

Avoid:

{
  "error": "NullReferenceException",
  "stackTrace": "at Service.UserHandler.Process()..."
}

Use:

{
  "type": "/problems/internal-error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred."
}

Summary

A well-designed REST API should:

• Define both success and error responses in the API specification.
• Use standard HTTP status codes only.
• Select the most specific status code available.
• Use 207 Multi-Status for batch and bulk operations requiring individual results.
• Use application/problem+json for detailed error responses.
• Never expose stack traces or internal implementation details.