Error Handling

How the client API reports errors.

Error Format

Client API errors return JSON with a detail field - either a string or a validation array:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "item_path"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Dashboard API routes use {"error": "message"} instead.

Status Codes

• 400 - validation error or bad request
• 401 - missing or invalid API key
• 403 - forbidden (wrong plan, no access to file)
• 404 - file, folder, or permission not found
• 409 - conflict (duplicate folder, already shared)
• 413 - file too large or storage quota exceeded
• 429 - rate limit exceeded (see Rate Limiting)

Examples

curl -X POST https://cloud.storra.host/api/v1/client/files/upload \
  -H "X-API-Key: sk_your_api_key_here"

Rate limited (429):

{ "detail": "Rate limit exceeded. Please try again later." }

Response includes Retry-After header (seconds).

Retries

Retry 429 and transient 5xx errors with exponential backoff. Respect Retry-After when present.