JSONKit
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.

{
  "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

successrequiredbooleanAlways false for error responses
statusrequiredintegerHTTP status code (e.g. 400, 401, 403, 404, 422, 429, 500)
error.coderequiredstringMachine-readable error identifier in SCREAMING_SNAKE_CASE
error.messagerequiredstringHuman-readable explanation of what went wrong
error.detailsoptionalarray<object>Per-field validation errors with field name, rule, and message
requestIdoptionalstringUnique request ID to include when reporting the issue to support
docsUrloptionalstringLink to error-specific documentation page
timestamprequiredstring (ISO 8601)Server time when the error was generated

Variants

MinimalSimple 404 not-found error with just code and message.
{
  "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.
{
  "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

One click loads this exact example into the tool — no copy-paste needed. Format it, validate it, explore the tree, or generate TypeScript types instantly.

FormatValidateExplore treeGenerate TypeScriptMinify

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.