Errors and limits
Error shape
Drive’s own errors are JSON with one field:
{"error": "file version mismatch"}
The message is for people reading logs; branch on the status code, not the text.
| Status | Meaning | Example error |
|---|---|---|
400 | Bad input | inline file content must be 300000 bytes or fewer, x-granite-grant must be a UUID |
401 | Missing or invalid credentials | always unauthorized |
403 | Authenticated, but not allowed: the grant is revoked or expired, doesn’t cover the request, or the action is one apps can’t take | always forbidden |
404 | No such file | file 0b3e8d2a-7c41-4f9e-a5d6-2c9b1e7f4a30 does not exist |
409 | Conflicts with the current state: a stale expected_version, a name already used in the folder, or a limit reached | file version mismatch, name "shopping.md" already exists in this directory, file limit reached: 1000 files allowed |
429 | An hourly limit was reached | <action> limit reached: <n> per hour |
5xx | Drive or a service it depends on failed | always internal error |
403 never says why. If your app could reach a file before and now gets
403, check the grant with Granite.
Drive fails closed: if it can’t confirm a grant with Granite, the request
fails with a 5xx and nothing is read or written. Retry 429 and 5xx
responses later, with backoff.
Parsing errors
These come from the web framework, before authentication, as plain text:
| Status | Cause | Example body |
|---|---|---|
400 | A path segment that should be a UUID isn’t | Invalid URL: Cannot parse `file_id` with value `not-a-uuid`: UUID parsing failed: invalid character: found `n` at 0 |
400 | The body is not valid JSON | Failed to parse the request body as JSON: EOF while parsing a value at line 1 column 12 |
415 | Missing Content-Type: application/json on a request with a JSON body | |
422 | Valid JSON, wrong fields: an unknown field, a wrong type, a missing required field | Failed to deserialize the JSON body into the target type: colour: unknown field `colour`, expected one of `name`, `content`, `mime_type`, `directory_id`, `tags` at line 1 column 20 |
413 | The body is over 2 MB | Failed to buffer the request body: length limit exceeded |
curl -sS -o /dev/null -w '%{http_code}\n' https://tj7hnhcvwir4n6rl5itdqut3mq0wdpke.lambda-url.us-east-1.on.aws/v1/files/not-a-uuid | grep -Fx 400
An unknown path answers 404 with an empty body.
Limits
Each person has these limits by default, shared by every app they use and the Drive app. Files in the trash still count.
| Limit | Default | When reached |
|---|---|---|
| Files | 1,000 | 409 |
| Folders | 200 | 409 |
| Storage | 250 MB | 409 |
Per request:
| Limit | Value | When over |
|---|---|---|
| File content sent by an app | 300,000 bytes | 400 |
| File and folder names | 255 characters | 400 |
| Tags | 50 per file, 80 characters each | 400 |
| Request body | 2 MB | 413 (plain text) |