Error Handling

All API errors follow a consistent format.

Error Object

{
  "code": "invalid_request",
  "message": "Human-readable description of the error",
  "request_id": "req_abc123",
  "metadata": {
    "field": "additional_context"
  }
}

Field	Type	Description
code	string	Machine-readable error code
message	string	Human-readable error description
request_id	string	Unique request ID for tracking (pattern: req_*)
metadata	map	Additional context about the error

HTTP Status Codes

Code	Meaning	When
200	OK	Successful request
400	Bad Request	Invalid request parameters or body
401	Unauthorized	Missing or invalid license key
403	Forbidden	License lacks required capabilities
404	Not Found	Resource does not exist
409	Conflict	Resource already exists (e.g., duplicate email/phone)
500	Internal Server Error	Unexpected server error

Common Error Codes

Request Errors

Code	HTTP	Description
invalid_request	400	Request body or parameters are malformed
validation_error	400	One or more fields failed validation
missing_field	400	A required field is missing

Authentication Errors

Code	HTTP	Description
unauthorized	401	No valid license key provided
forbidden	403	Insufficient permissions
license_expired	401	License has expired
license_invalid	401	License key is invalid

Resource Errors

Code	HTTP	Description
not_found	404	Requested resource does not exist
already_exists	409	Resource with same unique key exists
customer_not_found	404	Customer ID does not match any record

Processing Errors

Code	HTTP	Description
processing_error	500	Error during operation processing
provider_error	502	External provider returned an error
transaction_failed	400	Financial transaction could not be completed

Error Handling Example

curl -X GET https://host:8080/v1/customers/invalid_id \
  -H "Authorization: Bearer <license_key>"

{
  "code": "customer_not_found",
  "message": "No customer found with ID: invalid_id",
  "request_id": "req_7f3a2b1c",
  "metadata": {
    "customer_id": "invalid_id"
  }
}