# Errors

API errors return JSON with three fields:

```json
{
  "error": "File not found. List your files with GET /api/v1/files and use the key it returns.",
  "code": "file_not_found",
  "doc_url": "https://strovio.xyz/docs/errors#file_not_found"
}
```

`error` is a plain sentence that says what to do. `code` is stable; match on it, not on the sentence. `doc_url` links to the section below. `HEAD` requests return the status only, without a body. The SDK exposes these as `StrovioError.statusCode`, `code` and `docUrl`.

## invalid_api_key

Status 401. The request had no API key, a malformed one, or a key that was deleted.

Fix: send `Authorization: Bearer sk_live_...` with a key from [strovio.xyz/developer](https://strovio.xyz/developer). Check the environment variable is set in the process that sends the request. If the key was lost or deleted, create a new one. See [Create an account and an API key](https://strovio.xyz/docs/get-an-api-key).

## invalid_request

Status 400. A required field is missing or a value is out of range, for example a `limit` that is not a positive whole number, a missing `key` or `size`, or a multipart `s3Key` that does not match `key` and `access`.

Fix: read the `error` sentence, correct that field, and send the request again.

## file_not_found

Status 404. No file in your account matches the path or key.

Fix: list your files with `GET /api/v1/files?prefix=<part of the path>` and use the `key` it returns. Paths are case-sensitive and must match exactly; `a.txt` does not find `reports/a.txt`.

## ambiguous_key

Status 409. The same path exists as both a public and a private file, so the path alone does not say which one you mean. `HEAD` returns `409` without a body.

Fix: send the full key, `uploads/<account>/public/<path>` or `uploads/<account>/private/<path>`, from `GET /api/v1/files`.

## file_too_large

Status 413. The file is over 512 MB.

Fix: Strovio does not accept files over 512 MB. Split or compress the file. Under 512 MB, use a [multipart upload](https://strovio.xyz/docs/large-uploads) if a single request fails.

## storage_quota_exceeded

Status 413. This upload would take your account over its storage limit.

Fix: delete files you no longer need, or upgrade at [strovio.xyz/billing](https://strovio.xyz/billing).

## storage_limit_reached

Status 413, from `presign-put`. Your plan's storage is full or your trial or plan has ended. The body also has `usedBytes`, `limitBytes` and `upgrade: true`.

Fix: upgrade at [strovio.xyz/billing](https://strovio.xyz/billing) or delete files.

## upload_not_found

Status 400, from `POST /files/complete`. Storage has no object for this key yet.

Fix: finish the `PUT` to the `putUrl` first and check it returned `200`, then call complete with the same `key` and `access`.

## forbidden

Status 403, from `multipart/complete`. The `s3Key` belongs to another account.

Fix: use the `s3Key` returned by your own `multipart/start` call, with the same API key.

## internal_error

Status 500. Something failed on Strovio's side.

Fix: retry with exponential backoff, for example after 1, 2 and 4 seconds. If it keeps failing, check `https://strovio.xyz/api/health` and email support@strovio.xyz with the time and the endpoint.

## Errors outside the API

- SDK input checks (status 400) and timeouts (status 408) happen before or instead of a response; the message says which value to change.
- Share link downloads return plain text: see [Share a file with a link](https://strovio.xyz/docs/share-links).
- A signed URL that has expired returns an XML `AccessDenied` or `Request has expired` error from `s3.strovio.xyz`. Request a new URL with `GET /api/v1/files/{path}`.

---

Source: https://strovio.xyz/docs/errors
All docs for agents: https://strovio.xyz/llms.txt