Errors
Error taxonomy, response format, error types, common codes, handling strategies, and retry guidance.
Overview
The DMTR API returns structured error responses for all failure conditions: a stable taxonomy, a consistent response format, documented codes, and retry guidance.
Error response format
All errors return a JSON body with error object containing type, code, message, and optionally details. HTTP status codes indicate the category: 4xx for client errors, 5xx for server errors. Include the request_id from the response when contacting support.
Error types and examples
400 Bad Request — Invalid request
StableMalformed request, validation failure, or invalid parameters.
{
"error": {
"type": "invalid_request",
"code": "invalid_parameter",
"message": "Invalid value for 'limit': must be between 1 and 100",
"details": {
"field": "limit",
"reason": "out_of_range"
}
},
"request_id": "req_01HXYZ789ABC"
}401 Unauthorized — Authentication error
StableMissing or invalid credentials.
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The API key provided is invalid or has been revoked"
},
"request_id": "req_01HXYZ789DEF"
}403 Forbidden — Permission denied
StableValid credentials but insufficient permissions.
{
"error": {
"type": "permission_denied",
"code": "insufficient_scope",
"message": "Your API key does not have permission to perform this action",
"details": {
"required_scope": "positions:write"
}
},
"request_id": "req_01HXYZ789GHI"
}404 Not Found
StableResource does not exist or is not accessible.
{
"error": {
"type": "not_found",
"code": "resource_not_found",
"message": "No position found with entity_id 'pos_invalid'"
},
"request_id": "req_01HXYZ789JKL"
}422 Unprocessable Entity — Validation error
StableRequest body or parameters failed semantic validation.
{
"error": {
"type": "invalid_request",
"code": "validation_failed",
"message": "Request validation failed",
"details": {
"errors": [
{
"field": "asset.fund_id",
"message": "Fund ID is required for fund_lp_interest type"
}
]
}
},
"request_id": "req_01HXYZ789MNO"
}429 Too Many Requests — Rate limit
StableToo many requests; retry after backoff.
{
"error": {
"type": "rate_limit",
"code": "rate_limit_exceeded",
"message": "Too many requests. Please retry after 60 seconds"
},
"request_id": "req_01HXYZ789PQR"
}500 Internal Server Error
StableServer-side failure; retry with exponential backoff.
{
"error": {
"type": "internal_error",
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
},
"request_id": "req_01HXYZ789STU"
}Error types table
| Type | HTTP Status | Description |
|---|---|---|
invalid_request | 400 | Malformed request, validation failure, or invalid parameters |
authentication_error | 401 | Missing or invalid credentials |
permission_denied | 403 | Valid credentials but insufficient permissions |
not_found | 404 | Resource does not exist or is not accessible |
conflict | 409 | State conflict (e.g., duplicate idempotency key) |
rate_limit | 429 | Too many requests; retry after backoff |
internal_error | 500 | Server-side failure; retry with exponential backoff |
Common error codes
Common codes include invalid_parameter (field-level validation), invalid_api_key, token_expired, insufficient_scope, resource_not_found, idempotency_key_reused, and rate_limit_exceeded. The details field may contain field-specific validation errors.
Handling errors
Map error types to user-facing messages or logging. For invalid_request, surface validation details to the user. For authentication_error and permission_denied, prompt re-authentication or scope upgrade. For not_found, handle gracefully in UI flows. For conflict, check idempotency and state before retry.
Retry guidance
Retry strategy: Retry rate_limit (429) and internal_error (500) with exponential backoff. Use the Retry-After header when present. Do not retry invalid_request, authentication_error, or permission_denied without fixing the underlying issue. For idempotent operations, retries are safe; for non-idempotent operations, use idempotency keys.