Skip to main content
All Natural API errors follow a standard JSON:API-style format with stable public codes and safe display copy.

​
Error response format

Every error response contains an errors array with one or more error objects: 
{
  "errors": [
    {
      "code": "insufficient_funds",
      "detail": "Insufficient funds.",
      "status": "409",
      "meta": {
        "supportId": "req_a1b2c3d4e5f6"
      }
    }
  ]
}
Each error object contains:
FieldTypeRequiredDescription
codestringYesStable lower-snake-case public error code (e.g., insufficient_funds)
detailstringYesSafe user-facing error message
statusstringYesHTTP status code as a string
sourceobjectNoLocation of the invalid request value, such as source.pointer
metaobjectYesMetadata containing supportId for troubleshooting

​
Metadata

Public error responses include meta.supportId by default. Internal/upstream metadata is kept in logs and traces, correlated by supportId.

​
Validation errors

Validation errors may include source.pointer for API clients: 
{
  "errors": [
    {
      "code": "invalid_value",
      "detail": "email: Invalid email address",
      "status": "422",
      "source": {
        "pointer": "/data/attributes/email"
      },
      "meta": {
        "supportId": "req_a1b2c3d4e5f6"
      }
    }
  ]
}