API Reference
Errors
Error response shape, error codes, limits, and recovery patterns.
This page summarizes standard error formats and common failure modes for Carrot API integrations.
Error response format
Typical error payload:
{
"statusCode": 400,
"errors": [
{
"code": "validationError",
"message": "Failed validating required field",
"id": "5g1XRgWZ0odA79dHJvcPP",
"timestamp": "1684766595"
}
]
}Error codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalidJson | Request body could not be decoded as JSON. |
| 400 | validationError | Request payload failed schema validation. |
| 401 | unauthorized | Access token is missing, invalid, or expired. |
| 403 | restrictedResource | Token does not have permission for this resource or environment. |
| 404 | objectNotFound | Resource does not exist or is not shared with token owner. |
| 409 | conflictError | Operation could not be completed due to data conflict. |
| 409 | PENDING_PROCESS_CONFLICT_ERROR | Requested document is still processing. Retry later. |
| 429 | Too Many Requests | Request rate exceeded allowed threshold. |
| 500 | internalServerError | Unexpected server-side failure. |
| 503 | serviceUnavailable | Service temporarily unavailable or request exceeded processing window. |
| 504 | gatewayTimeout | Upstream timeout/session expiration while completing request. |
For rate limits and quotas, see Rate Limits.
For error recovery patterns and retry strategies, see Error Handling.