> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterfall.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Common HTTP status codes and troubleshooting guidance.

Waterfall uses standard HTTP status codes for success and failure.

| Status | Meaning                        |
| ------ | ------------------------------ |
| `200`  | Success                        |
| `400`  | Invalid request payload/inputs |
| `401`  | Missing API key                |
| `403`  | Invalid API key                |
| `404`  | Resource/job not found         |
| `429`  | Rate limit exceeded            |
| `500`  | Internal server error          |

## Error response shape

All error responses return a JSON body with the following structure:

```json theme={null}
{
  "status": "error",
  "message": "Bad request",
  "error": ["Bad request"],
  "category": "VALIDATION",
  "code": "VALIDATION_BAD_REQUEST"
}
```

| Field      | Description                                                                                                                                         |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`   | Always `"error"`                                                                                                                                    |
| `message`  | Human-readable summary                                                                                                                              |
| `error`    | Array of error detail strings                                                                                                                       |
| `category` | Broad error group — e.g. `VALIDATION`, `NOT_FOUND`, `RATE_LIMIT`                                                                                    |
| `code`     | Specific error type — for the full list refer to the [OpenAPI specification](https://waterfall-io-public.s3.us-east-1.amazonaws.com/api_specs.yaml) |

## Troubleshooting checklist

* Validate request body structure.
* Confirm API key is present and valid.
* Retry safely for `429` and transient `5xx`.