Skip to main content

​
Error Format

{
  "error": {
    "code": "error_code",
    "message": "Human-readable message",
    "details": []
  }
}

​
Error Codes

​
400 Bad Request

Code: validation_error or invalid_json Request failed validation. Check the details array for specifics. 
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "field": "context.billable_customer_id",
        "code": "required",
        "message": "billable_customer_id is required"
      }
    ]
  }
}
Field Error Codes:
CodeMeaning
requiredField is required but missing
invalid_typeField has wrong type
invalid_valueField value not in allowed set
too_smallValue below minimum
too_largeValue above maximum
invalid_formatValue format is invalid
Common causes:
  • Missing required fields (provider, model, usage, context.billable_customer_id)
  • Invalid enum values for provider
  • Request body isn’t valid JSON

​
401 Unauthorized

Code: unauthorized API key is missing or invalid. 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}
Check:
  • X-Api-Key header is present
  • Key is correct and active in your dashboard

​
207 Multi-Status

Some transactions succeeded, some failed. Check results for details. 
{
  "status": "partial_success",
  "events_queued": 1,
  "events_failed": 1,
  "results": [
    { "transaction_index": 0, "message_id": "abc123" },
    { "transaction_index": 1, "error": "billable_customer_id is required" }
  ]
}

​
500 Internal Server Error

Code: internal_error Server-side issue. Safe to retry. 
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}