Error Catalog
DMTR error codes and resolutions.
Overview
This catalog lists DMTR API error codes, their meanings, and recommended resolutions. Errors follow a consistent structure with a code, message, and optional details. Use this reference when handling errors in your integration.
Error structure
All API errors return a JSON body with code, message, and optionally details. The code is a stable identifier for programmatic handling. The message is human-readable. details may include field-level validation errors or context.
Error categories
Errors fall into categories: authentication, authorization, validation, rate limiting, not found, conflict, and server errors. Each category has a corresponding HTTP status code. See API Errors for the error taxonomy.
Common errors and resolutions
| Code | HTTP | Description | Resolution |
|---|---|---|---|
invalid_api_key | 401 | API key missing or invalid | Check Authorization header, rotate key if compromised |
forbidden | 403 | Insufficient permissions | Verify API key scopes, check resource ownership |
validation_error | 400 | Request validation failed | Check details for field errors, fix request body |
rate_limit_exceeded | 429 | Too many requests | Implement backoff, respect Retry-After header |
not_found | 404 | Resource not found | Verify ID, check environment (sandbox vs production) |
conflict | 409 | State conflict | Retry with fresh data, resolve concurrent modification |
invalid_api_key
Stable
{
"code": "invalid_api_key",
"message": "The API key provided is invalid or has been revoked.",
"details": {
"hint": "Check your Authorization header format: Bearer <key>"
}
}rate_limit_exceeded
Stable
{
"code": "rate_limit_exceeded",
"message": "Too many requests. Please retry after the specified time.",
"retry_after": 30
}validation_error
Stable
{
"code": "validation_error",
"message": "Request validation failed.",
"details": {
"fields": [
{
"field": "quantity",
"error": "must be a positive integer"
},
{
"field": "position_id",
"error": "required"
}
]
}
}Full catalog
The complete error catalog is maintained in the API specification. Error codes are versioned with the API; deprecated codes are documented in API versioning.