Error Codes

Error Response Format

All errors return a JSON body:

{
  "error": "Error description",
  "status": 409,
  "code": "CAS_ERROR"
}

Error	Status	Code	When
CASError	409	`CAS_ERROR`	`expected_cid` 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.
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.

The most common error you'll encounter is CASError (409). The response includes both CIDs:

{
  "error": "CAS conflict",
  "expected": "bafyreig...",
  "actual": "bafyreih...",
  "status": 409
}

Recovery:

Validation errors include details about which fields failed:

{
  "error": "Validation failed",
  "status": 400,
  "details": [
    { "path": "properties.name", "message": "Required" }
  ]
}