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 in wallet wal_abc123. Requested $5,000.00 but only $2,500.00 available.",
      "status": 400,
      "meta": {
        "wallet_id": "wal_abc123",
        "requested_amount": "500000",
        "available_amount": "250000",
        "currency": "USD"
      }
    }
  ]
}
Each error object contains:
FieldTypeRequiredDescription
codestringYesMachine-readable error code (e.g., INSUFFICIENT_BALANCE)
detailstringYesHuman-readable error message
statusintegerYesHTTP status code
metaobjectNoAdditional context for recovery

​
When meta is included

  • Amounts/limits involved — wallet_id, requested_amount, available_amount, currency
  • Field validation errors — field, constraint
  • Retry logic — retry_after, window
  • Request tracing — supportId

​
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 one error object per invalid field, making it easy to display inline field errors: 
{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "detail": "Field required",
      "status": 422,
      "meta": {
        "field": "amount",
        "constraint": "required"
      }
    },
    {
      "code": "VALIDATION_ERROR",
      "detail": "Invalid email format",
      "status": 422,
      "meta": {
        "field": "email",
        "constraint": "value_error"
      }
    }
  ]
}