The Definitive Guide to Structured Error Responses for AI Agents

{
  "error": true,
  "code": "INVALID_PARAMETER",
  "message": "Field 'email' must be a valid email address.",
  "request_id": "req_abc123def456",
  "details": [
    {
      "field": "email",
      "value": "not-an-email",
      "constraint": "Must match pattern: *@*.*"
    }
  ]
}

{
  "error": true,
  "code": "AUTH_REQUIRED",
  "message": "Bearer token is missing or expired.",
  "request_id": "req_xyz789ghi012",
  "details": [
    {
      "header": "Authorization",
      "expected": "Bearer <token>",
      "docs": "https://docs.example.com/auth"
    }
  ]
}

{
  "error": true,
  "code": "INSUFFICIENT_SCOPE",
  "message": "Token lacks 'orders:write' scope.",
  "request_id": "req_pqr345stu678",
  "details": [
    {
      "required_scope": "orders:write",
      "current_scopes": ["orders:read", "products:read"],
      "upgrade_url": "https://dashboard.example.com/api-keys"
    }
  ]
}

{
  "error": true,
  "code": "NOT_FOUND",
  "message": "Product with ID 'prod_999' does not exist.",
  "request_id": "req_mno901vwx234",
  "details": [
    {
      "resource_type": "product",
      "resource_id": "prod_999",
      "suggestion": "Use GET /products to list available products."
    }
  ]
}

{
  "error": true,
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded. 100 requests per minute allowed.",
  "request_id": "req_jkl567yza890",
  "retry_after": 32,
  "details": [
    {
      "limit": 100,
      "window": "60s",
      "remaining": 0,
      "reset_at": "2026-04-15T14:30:32Z"
    }
  ]
}

// middleware/agentErrors.js
function agentErrorHandler(err, req, res, next) {
  const requestId = req.headers['x-request-id'] || crypto.randomUUID()
  const status = err.status || 500
  res.status(status).json({
    error: true,
    code: err.code || 'INTERNAL_ERROR',
    message: err.expose ? err.message : 'An internal error occurred.',
    request_id: requestId,
    ...(err.retryAfter && { retry_after: err.retryAfter }),
    ...(err.details && { details: err.details }),
  })
}
// app.use(agentErrorHandler) — after all routes

// lib/apiError.ts
export function apiError(
  status: number, code: string, message: string,
  details?: Record<string, unknown>[]
) {
  const requestId = crypto.randomUUID()
  return Response.json(
    { error: true, code, message, request_id: requestId,
      ...(details && { details }) },
    { status, headers: { 'X-Request-ID': requestId } }
  )
}
// Usage: return apiError(400, 'INVALID_PARAM', 'Email required')

# middleware/agent_errors.py
import uuid
from rest_framework.views import exception_handler

def agent_exception_handler(exc, context):
    response = exception_handler(exc, context)
    if response is not None:
        request_id = str(uuid.uuid4())
        response.data = {
            "error": True,
            "code": getattr(exc, "default_code", "ERROR"),
            "message": response.data.get("detail", str(exc)),
            "request_id": request_id,
        }
        response["X-Request-ID"] = request_id
    return response

# app/controllers/concerns/agent_errors.rb
module AgentErrors
  extend ActiveSupport::Concern
  included do
    rescue_from StandardError do |e|
      request_id = request.request_id
      status = e.respond_to?(:status) ? e.status : 500
      render json: {
        error: true,
        code: e.class.name.demodulize.underscore.upcase,
        message: Rails.env.production? ? "Internal error" : e.message,
        request_id: request_id
      }, status: status
    end
  end
end