> ## Documentation Index
> Fetch the complete documentation index at: https://devtools.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, such as `VALIDATION`, `NOT_FOUND`, `RATE_LIMIT` |
| `code` | Specific error type. See the full list in 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`.