# Know what to do next.

API failures return a JSON object with an `error` code. A successful activity read can also describe a processing failure through `status: "failed"` and `error_code`.

## Request errors

| HTTP | Code | Action |
| --- | --- | --- |
| `400` | `empty_body` | Send a FIT file as the request body |
| `400` | `invalid_list_query` | Check status, search length, limit, and offset |
| `401` | `unauthorized` | Check the bearer key and target environment |
| `404` | `activity_not_found` | Check the ID and workspace; another workspace's activity is also hidden as 404 |
| `404` | `not_found` | Check the method and API path |
| `409` | `activity_not_ready` | Poll status before requesting decoded JSON |
| `413` | `file_too_large` | Use a file of 4 MiB or less |
| `415` | `send_raw_fit_bytes` | Use a supported binary content type |
| `422` | `invalid_fit`, `invalid_fit_length`, `invalid_fit_crc` | Export the original single FIT file again; check for truncation or corruption |
| `503` | `stored_object_unavailable`, `service_unavailable` | Retry with a bounded delay; keep the activity ID |
| `503` | `beta_not_open` | The public site is available, but the hosted beta API has not opened |

Browser-only routes can also return `browser_signin_required` or `origin_not_allowed`. They are internal to the signed-in workspace; server integrations should use `/v1/`.

## Processing failures

| Code | Meaning |
| --- | --- |
| `not_an_activity` | The file has no activity file identifier or no session messages |
| `fit_decode_failed` | The decoder could not read the file successfully |
| `decoded_limit_exceeded` | The decoded message count or size exceeded beta limits |
| `processing_unavailable` | Repeated dispatch attempts did not produce a completed result |

Validation codes can also appear during processing if the stored original cannot pass revalidation. For a failed activity, the `/data` endpoint returns HTTP `409` with its processing error code.

## Preserve a useful reference

Keep the activity ID, HTTP status, and error code when diagnosing a problem. Do not log API keys or complete activity files. If an upload response is lost, the same file can be uploaded again safely within the same workspace.