Skip to main content
All Natural API errors follow a standard format with structured metadata to enable programmatic error recovery and autonomous agent decision-making.

​
Error response format

Every error response contains an errors array with one or more error objects: 
{
  "errors": [
    {
      "code": "INSUFFICIENT_BALANCE",
      "detail": "Insufficient balance. Requested $5,000.00 but only $2,500.00 available.",
      "status": 400,
      "meta": {
        "requestedAmount": 500000,
        "availableAmount": 250000,
        "currency": "USD",
        "supportId": "req_a1b2c3d4e5f6"
      }
    }
  ]
}
Each error object contains:
FieldTypeRequiredDescription
codestringYesMachine-readable error code (e.g., INSUFFICIENT_BALANCE)
detailstringYesHuman-readable error message
statusintegerYesHTTP status code
metaobjectYesMetadata including supportId for troubleshooting

​
When meta includes additional context

  • Amounts/limits — requestedAmount, availableAmount, currency
  • Field validation errors — formErrors, fieldErrors
  • Retry logic — retryAfter
  • Request tracing — supportId (always present)

​
When meta is omitted

  • Generic 500 errors (no additional context available)
  • Security errors (to avoid leaking internal details)
  • Simple not-found errors (detail message is sufficient)

​
Validation errors

Validation errors return structured field-level details in meta: 
{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "detail": "email: Invalid email address",
      "status": 422,
      "meta": {
        "formErrors": [],
        "fieldErrors": {
          "email": ["Invalid email address"]
        },
        "supportId": "req_a1b2c3d4e5f6"
      }
    }
  ]
}