Error Handling
Last updated: March 2026
When a request fails, the API returns a structured error response with a status code, error code, and human-readable message.
Error Format
All error responses include a
request_id for correlation with support and a structured error object:json
{
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"error": {
"code": "NOT_FOUND",
"message": "Deal with id 999 not found"
}
}The
request_id matches the value logged in usage tracking, so it can be referenced when contacting support.Status Codes
| Code | Meaning | When |
|---|---|---|
200 | OK | Successful read or update |
201 | Created | Successful resource creation |
400 | Bad Request | Invalid request body, missing required fields, malformed query parameters |
401 | Unauthorized | Missing, invalid, or expired authentication token |
403 | Forbidden | Valid token but insufficient permissions |
404 | Not Found | Resource doesn't exist or isn't accessible to the authenticated user |
409 | Conflict | Idempotency conflict (different request body with same idempotency key) |
422 | Unprocessable Entity | Valid JSON but semantically invalid (e.g., invalid enum value) |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Unexpected server error |
Common Errors
Missing authentication
json
{
"request_id": "...",
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
}Resource not found
Returns
404 both when a resource doesn't exist and when the authenticated user doesn't have access to it. This prevents information leakage about resource existence.json
{
"request_id": "...",
"error": {
"code": "NOT_FOUND",
"message": "Deal with id 999 not found"
}
}Validation error
json
{
"request_id": "...",
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid value for field 'loan_type': must be one of [acquisition, refinance, construction, ...]"
}
}Rate limited
json
{
"request_id": "...",
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 30 seconds."
}
}