API Error Response Analyzer

Analyzing API Error Responses for Quality and Compliance

API error responses are the interface between your backend and developers consuming your API. A well-designed error response includes a machine-readable error code, a human-readable message, request traceability identifiers, and context about what went wrong without exposing internal implementation details. Poorly designed errors — missing trace IDs, exposed stack traces, or non-standard structures — make debugging difficult for consumers and create security vulnerabilities by leaking server internals.

The API Error Response Analyzer inspects JSON error payloads for quality, traceability, security, and RFC 7807 (Problem Details) compliance. It evaluates whether your errors provide enough context for debugging while keeping sensitive information properly contained. Each finding includes specific recommendations for improving error response design to meet industry best practices.

Traceability and Correlation

Modern distributed systems require traceability identifiers in error responses so that consumers can reference specific failures when contacting support or filing bug reports:

• Request ID: A unique identifier for the specific request that failed (requestId, request_id, x-request-id)
• Trace ID: Distributed tracing identifier linking the request across services (traceId, trace_id)
• Correlation ID: Business-level correlation for tracking related operations
• Timestamp: When the error occurred (ISO 8601 format)

The analyzer flags error responses missing traceability fields and recommends adding at minimum a request ID and timestamp. Without these, debugging production issues requires log correlation by time window — unreliable in high-throughput systems.

Security: Stack Trace and Internal Data Exposure

Error responses must never expose server internals to API consumers. The analyzer detects:

• Stack traces: Full exception traces revealing file paths, line numbers, and framework internals
• Database errors: Raw SQL errors exposing table names, column names, or query structure
• Internal paths: Server file system paths like /var/www/app/controllers/UserController.php
• Framework details: Version numbers or framework-specific error formats that aid targeted attacks
• Sensitive data in context: User emails, API keys, or tokens echoed back in error details

Each exposure type represents a different risk level — stack traces enable targeted exploits, database errors reveal schema structure for injection attacks, and framework details allow attackers to search for known vulnerabilities in specific versions.

RFC 7807 Problem Details Compliance

RFC 7807 defines a standard format for HTTP API error responses that many organizations adopt for consistency. The analyzer checks for compliance with its required and recommended fields:

• type — A URI identifying the error type (required by RFC 7807)
• title — A short human-readable summary of the problem type
• status — The HTTP status code (should match the response status)
• detail — Human-readable explanation specific to this occurrence
• instance — URI identifying the specific occurrence of the problem

Even if not strictly following RFC 7807, the analyzer evaluates whether error responses contain equivalent fields under different names and suggests migration paths toward the standard format for improved interoperability.

Code Examples

Poor vs Well-Designed API Error Response

// POOR: Exposes internals, no traceability
{
  "error": true,
  "message": "SQLSTATE[42S02]: Table 'users_v2' not found",
  "stack": "at /var/www/app/Models/User.php:142\n  at PDO->query()...",
  "code": 500
}

// GOOD: RFC 7807 compliant, secure, traceable
{
  "type": "https://api.example.com/errors/resource-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "The requested user profile does not exist or has been deactivated.",
  "instance": "/users/abc-123",
  "requestId": "req_7f8a9b2c",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "timestamp": "2024-03-15T10:30:00Z"
}

Standards & Specifications

• RFC 7807 — Problem Details for HTTP APIs — Defines the standard format for machine-readable error responses in HTTP APIs