API Design

Error Response JSON Example

A standardized JSON example for API error responses — includes HTTP status code, error code, human-readable message, and field-level validation errors. Copy-ready for REST APIs.

JSON

Open in Formatter

{
  "success": false,
  "status": 422,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields.",
    "details": [
      {
        "field": "email",
        "rule": "format",
        "message": "Must be a valid email address."
      },
      {
        "field": "phone",
        "rule": "pattern",
        "message": "Must match pattern +91-XXXXX-XXXXX."
      },
      {
        "field": "dateOfBirth",
        "rule": "max",
        "message": "User must be at least 18 years old."
      }
    ]
  },
  "requestId": "req_Xm9pKv3LqR",
  "timestamp": "2025-05-01T10:30:00Z",
  "docsUrl": "https://docs.example.com/errors/VALIDATION_ERROR"
}

Field Reference

successbooleanrequiredAlways false for error responses

statusintegerrequiredHTTP status code (e.g. 400, 401, 403, 404, 422, 429, 500)

error.codestringrequiredMachine-readable error identifier in SCREAMING_SNAKE_CASE

error.messagestringrequiredHuman-readable explanation of what went wrong

error.detailsarray<object>optionalPer-field validation errors with field name, rule, and message

requestIdstringoptionalUnique request ID to include when reporting the issue to support

docsUrlstringoptionalLink to error-specific documentation page

timestampstring (ISO 8601)requiredServer time when the error was generated

Variants

MinimalSimple 404 not-found error with just code and message.

Minimal

Open in Formatter

{
  "success": false,
  "status": 404,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource could not be found."
  },
  "timestamp": "2025-05-01T10:30:00Z"
}

ExtendedRate-limit exceeded error with retry-after, quota details, and support link.

Extended

Open in Formatter

{
  "success": false,
  "status": 429,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded the API rate limit. Please wait before retrying.",
    "details": [
      {
        "field": null,
        "rule": "rateLimit",
        "message": "Limit of 1000 requests per hour reached."
      }
    ],
    "retryAfter": 1800,
    "quota": {
      "limit": 1000,
      "used": 1000,
      "resetAt": "2025-05-01T11:00:00Z"
    }
  },
  "requestId": "req_Ym2pRt8qNk",
  "docsUrl": "https://docs.example.com/errors/RATE_LIMIT_EXCEEDED",
  "timestamp": "2025-05-01T10:30:00Z"
}

Common Use Cases

→Standardizing error response shapes across all API endpoints for consistent client-side handling
→Surfacing field-level validation errors in form UIs without custom parsing logic
→Enabling automated error monitoring by matching on the machine-readable error.code

errorvalidationREST API4xx5xxHTTP

Validate or format this JSON

Paste the example above into JSONKit's tools to validate, minify, or explore the structure interactively.

Format →Validate →Minify →

Frequently Asked Questions

Use 422 Unprocessable Entity for semantic validation failures (valid JSON structure but invalid field values). Use 400 Bad Request for malformed JSON or missing required fields. 5xx codes are reserved for server-side errors.

String codes like VALIDATION_ERROR or NOT_FOUND let clients branch logic without parsing the human-readable message string, which may change between API versions.

Never expose stack traces to clients in production — they reveal internal implementation details and are a security risk. Log them server-side and reference them via requestId.

Related JSON Examples

API DesignREST API ResponseGeneric REST API response wrapper with data payload, status, and pagination meta.API DesignPagination ResponsePaginated list response JSON with offset, cursor, total, and navigation links.AuthenticationJWT PayloadJWT payload JSON with standard RFC 7519 claims and custom role/permission fields.