Errors reference

All error responses returned by our APIs follow the following JSON format.

Field Descriptions

Field	Type	Description
`error_code`	string	Unique identifier for the specific error case, used programmatically
`error_type`	string	Category of the error (e.g., `validation`, `authentication`, `internal_error`)
`message`	string	Human-readable message describing the error
`details`	array	(Optional) List of field-specific validation errors
`details[].field`	string	Name of the field that caused the error
`details[].description`	string	Description of what went wrong with that field
`trace_id`	string	(Optional) Unique identifier for tracing the request across services

Example

Basic response

{
  "error_code": "service_unavailable",
  "error_type": "internal_error",
  "message": "an unexpected error occurred"
}

Full response

{
  "error_code": "invalid_request",
  "error_type": "validation",
  "message": "invalid request data",
  "details": [
    {
      "field": "instrument_id",
      "description": "invalid instrument_id format"
    }
  ],
  "trace_id": "trx-123"
}

Error codes

`error_code`	HTTP Status	Description
`service_unavailable`	503	The service is temporarily down or overloaded
`internal_server_error`	500	An unexpected internal error occurred
`resource_not_found`	404	The requested resource was not found
`invalid_request`	400	The request is malformed or contains invalid data
`unauthorized_request`	401	The request lacks valid authentication credentials
`resource_locked`	423	The resource is currently locked due to a concurrent op

Error types

`error_type`	Description	Typical Scenario
`internal_error`	Generic internal server error, unexpected and not recoverable by the client	Server bug, panic, or unknown exception
`unavailable`	The service is temporarily unavailable or under maintenance	Service overload, dependency failure
`unauthorized`	Missing or invalid authentication	No token, invalid credentials
`not_found`	Requested entity or resource doesn't exist	ID does not match a stored resource
`validation`	One or more input fields are invalid	Missing required fields, wrong types
`concurrency`	A resource is locked or being processed in parallel	Concurrent modification, distributed locking