Error handling

Handle API errors by status and machine-readable error code.

API errors include an HTTP status, a stable code, a human-readable message, and optional debugging details. Use the status for broad handling and code for specific recovery behavior.

Error response

{
  "status": 422,
  "code": "validation_error",
  "message": "Request validation failed",
  "request_id": "req_abc123",
  "additional_data": {
    "errors": [
      {
        "field": "query.limit",
        "message": "Too big: expected number to be <=100"
      }
    ]
  }
}

Field	Meaning
`status`	HTTP status code
`code`	Stable error code for programmatic handling
`message`	Human-readable summary
`request_id`	Request identifier for support and debugging
`additional_data`	Optional details such as field validation errors

Status codes

Status	Meaning	Action
`400`	Invalid request	Check the request syntax.
`401`	Invalid or missing key	Verify the key with `/v2/me`.
`403`	Missing permission	Create a key with the required scope.
`404`	Resource not found	Check the path and resource ID.
`422`	Validation failed	Fix the fields listed in `additional_data`.
`429`	Rate limit exceeded	Wait for `Retry-After` before retrying.
`500`	Server error	Retry conservatively with backoff.

See Rate limits for throttling behavior.

Handle errors in code

const response = await fetch('https://api.cevoid.com/v2/posts?limit=250', {
  headers: { Authorization: `Bearer ${process.env.CEVOID_API_KEY}` }
});

if (!response.ok) {
  const error = await response.json();

  console.error({
    status: error.status,
    code: error.code,
    message: error.message,
    requestId: error.request_id
  });
}

Log request_id for every failed request. Do not retry 401, 403, 404, or 422 until you change the request.