Error Codes

All API errors follow a consistent format. Use the error code and request ID for debugging and support requests.

Error Response Format

Error response

json

{
  "error": "validation_error",
  "message": "Field 'gross_pay' must be a positive integer.",
  "request_id": "req_abc123def456",
  "details": [
    { "field": "gross_pay", "code": "invalid_type", "expected": "integer" }
  ]
}

HTTP Status Codes

Status	Code	Description
400	bad_request	Invalid JSON, missing fields, or malformed request
401	unauthorized	Invalid API key or expired token
403	forbidden	API key lacks required scope or permission
404	not_found	Resource does not exist
409	conflict	Resource already exists or state conflict
422	validation_error	Request body fails schema validation
429	rate_limited	Rate limit exceeded, check headers
500	internal_error	Server error — contact support with request_id

Common Errors

Invalid API Key

Ensure your key starts with the correct prefix for your environment.

json

{
  "error": "unauthorized",
  "message": "Invalid or expired API key.",
  "request_id": "req_xyz789"
}

Missing Scope

Your API key or token lacks the required scope for this endpoint.

json

{
  "error": "forbidden",
  "message": "Missing required scope: write:vault",
  "request_id": "req_def456"
}