Reference
Error Codes
HTTP error codes and error types returned by the Arke API.
Error Response Format
All errors return a JSON body with the following structure:
{
"error": "CAS_FAILURE",
"message": "CAS failure: expected tip bafyreig..., got bafyreih..."
}Errors may include additional context in a details field:
{
"error": "NOT_FOUND",
"message": "Entity not found: 01JEXAMPLE123456789012345",
"details": {
"resource": "Entity",
"identifier": "01JEXAMPLE123456789012345"
}
}Error Types
| Error | Status | Code | When |
|---|---|---|---|
| CASError | 409 | CAS_FAILURE | expect_tip doesn't match the current tip. Another update occurred since you last read the entity. |
| NotFoundError | 404 | NOT_FOUND | Entity, collection, or resource doesn't exist. |
| ValidationError | 400 | VALIDATION_ERROR | Request body or parameters are invalid. |
| ConflictError | 409 | CONFLICT | Resource already exists (e.g., duplicate creation). |
| ForbiddenError | 403 | FORBIDDEN | Valid authentication but insufficient permissions for the requested action. |
| UnauthorizedError | 401 | UNAUTHORIZED | Missing or invalid authentication token/key. |
| StorageError | 503 | STORAGE_ERROR | R2 or D1 backend is temporarily unavailable. |
| DurableObjectError | 429 | DO_INFRASTRUCTURE_ERROR | Infrastructure overloaded. Retry after the duration specified in the Retry-After header. |
| InternalError | 500 | INTERNAL_ERROR | An unexpected server error occurred. |
Handling CAS Conflicts
The most common error you'll encounter is CASError (409). The response includes both CIDs in the details field:
{
"error": "CAS_FAILURE",
"message": "CAS failure: expected tip bafyreig..., got bafyreih...",
"details": {
"expect": "bafyreig...",
"actual": "bafyreih..."
}
}Recovery:
- Fetch the entity again (the
actualCID is now the tip) - Reapply your changes to the new version
- Retry the update with the new
expect_tip
Validation Errors
Validation errors include details about which fields failed:
{
"error": "VALIDATION_ERROR",
"message": "Validation failed",
"details": {
"path": "properties.name",
"message": "Required"
}
}Infrastructure Errors
When the Durable Object infrastructure is overloaded, the API returns a 429 status with a Retry-After header:
{
"error": "DO_INFRASTRUCTURE_ERROR",
"message": "Infrastructure overloaded during update for entity 01JEXAMPLE...",
"details": {
"operation": "update",
"entityId": "01JEXAMPLE123456789012345",
"original_error": "Durable Object subrequest failed"
}
}Check the Retry-After header (default: 5 seconds) before retrying.