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

# Error Handling

> Understand how Spidra API errors work and how to handle them

Spidra returns consistent error responses using standard HTTP status codes and descriptive messages. If something goes wrong with your request—like invalid input, missing authentication, or rate limits—you’ll receive a clear JSON error object.

## Error Response Format

```json theme={null}
{
	"status": "error",
	"message": "Detailed error explanation"
}
```

## Common Error Codes

| Status Code               | Description                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------- |
| 400 Bad Request           | The request was malformed or missing required parameters.                              |
| 401 Unauthorized          | Authentication failed. Check your API key.                                             |
| 403 Forbidden             | You do not have permission to access this resource.                                    |
| 404 Not Found             | The requested resource does not exist.                                                 |
| 429 Too Many Requests     | You have exceeded a rate limit. See the `code` field for which one.                    |
| 503 Service Unavailable   | The service is temporarily at capacity. Retry after the `retry_after` value (seconds). |
| 500 Internal Server Error | An unexpected error occurred on the server.                                            |

## Error Codes

Some errors include a `code` field with a machine-readable identifier:

| Code                    | Status | Meaning                                                                                    |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------ |
| `TOO_MANY_PENDING_JOBS` | 429    | You have too many jobs currently queued. Wait for some to complete before submitting more. |
| `SERVICE_BUSY`          | 503    | The server queue is at capacity across all users. Retry after `retry_after` seconds.       |
| `PAYMENT_OVERDUE`       | 402    | Your payment is overdue. Update your payment method to continue.                           |

```json theme={null}
{
  "status": "error",
  "message": "The scraping service is currently at capacity. Please retry in a few minutes.",
  "code": "SERVICE_BUSY",
  "retry_after": 60
}
```