Errors

The HTTP status code carries the primary signal. The response body shape depends on the kind of failure: regular errors return {"detail": "<message>"}, request-validation failures return FastAPI's structured detail array.

Regular errors#

Anything raised through the normal exception path — auth rejected, permission denied, resource not found, conflict, rate-limit, server error — comes back as:

1

{"detail": "Permission denied: WRITE on file/fil_01J3M"}

The HTTP status code tells you the class. The detail string is human-readable; surface it in UIs or logs but don't parse it.

Validation errors (422)#

When a request body fails Pydantic validation, FastAPI returns its standard structured error with a list of issues. detail is an array, not a string:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "detail": [
    {
      "loc": ["body", "role"],
      "msg": "Input should be 'owner', 'admin', 'contributor' or 'reader'",
      "type": "enum"
    },
    {
      "loc": ["body", "expires_in_days"],
      "msg": "Input should be less than or equal to 365",
      "type": "less_than_equal"
    }
  ]
}

Each entry has:

• loc — a path from the request root to the failing field (e.g., ["body", "role"], ["query", "limit"])
• msg — human-readable description
• type — the validator kind that fired (enum, missing, string_too_short, etc.)

Parse this on the client side to render field-level error messages.

Detecting the shape#

detail can be either a string or an array. The two shapes never appear together. Practical client code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import httpx

resp = httpx.post(url, json=payload, headers={"Authorization": f"Bearer {token}"})
if resp.status_code >= 400:
    body = resp.json()
    detail = body.get("detail")
    if isinstance(detail, list):
        # Validation errors — show field-by-field
        for issue in detail:
            field = ".".join(str(x) for x in issue["loc"])
            print(f"{field}: {issue['msg']}")
    else:
        # Regular error — single message
        print(f"HTTP {resp.status_code}: {detail}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

const resp = await fetch(url, { method: "POST", body: JSON.stringify(payload), headers });
if (!resp.ok) {
  const body = await resp.json();
  if (Array.isArray(body.detail)) {
    for (const issue of body.detail) {
      const field = issue.loc.join(".");
      console.error(`${field}: ${issue.msg}`);
    }
  } else {
    console.error(`HTTP ${resp.status}: ${body.detail}`);
  }
}

Retry strategy#

Streaming errors#

For file downloads, an error after response headers are sent produces a truncated body — your client must verify the full Content-Length (or the file's checksum_sha256) before treating a stream as complete.

For WebSocket connections, errors typically arrive as connection-close codes. The custom close codes ScaiDrive uses:

Standard WebSocket codes (1000, 1001, 1006, ...) carry their usual meaning.

Known gaps#

Two things this API doesn't have yet, worth knowing about:

• No machine-readable error codes. The detail string is the only error identifier. If you're building robust error handling, branch on HTTP status code + the operation you were performing, not on substring matching the message.
• No request ID propagation. Responses don't include an X-Request-Id header or a body-level request identifier today. When filing support tickets, include the request timestamp, status code, full URL, and the error message — that's the highest-fidelity correlation we can offer right now.

Both are tracked as planned improvements; this page will be updated when they ship.

What's next#

• Rate Limiting — how 429s are produced and how to back off.
• Troubleshooting — what to check when specific status codes appear.