---
title: "Errors and billing"
description: "Understand status codes, retries, timeouts, and when a solve is charged."
---

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

# Errors and billing

Every error uses the same JSON envelope:

```json
{
  "success": false,
  "message": "description of what went wrong"
}
```

Check both the HTTP status and `success`. Do not assume a response body contains
`data.solution` unless `success` is `true`.

## Status codes

| Status | Typical message | What to do |
| --- | --- | --- |
| `400` | `Request body could not be decoded` | Fix malformed JSON or task data. |
| `400` | `provided url for task is invalid` | Send a valid absolute HTTP(S) URL. |
| `401` | `X-Api-Key header is missing` | Add the authentication header. |
| `401` | `User provided an empty or invalid API key` | Replace or correct the key. |
| `401` | `URL is blacklisted` | Do not retry this target. |
| `402` | `insufficient balance` | Add balance or use another active package. |
| `403` | Key/package restriction message | Check expiry, status, quota, and allowed tasks. |
| `404` | `Task not found` | Use a supported `task_type`. |
| `429` | `Concurrency limit reached for this API key` | Wait for an in-flight solve to finish, then retry. |
| `500` | Solver or service error | Retry with backoff if the request is safe to repeat. |
| `504` | `task timed out` | Retry with backoff; the failed attempt is refunded. |

## Charging rules

For pay-as-you-go and bundle keys, usage is reserved before contacting the
solver. It is automatically restored when the solve fails, returns an error, or
times out. Successful solves keep the charge or quota debit.

Preflight rejections—such as invalid authentication, a blocked URL, an unknown
task, or an exceeded concurrency limit—do not start a solve.

> **30-second execution limit**
>
> A single task can run for at most 30 seconds. A timed-out request returns
> `504` when possible and does not consume pay-as-you-go balance or bundle
> quota.

Source: https://docs.uncaptcha.io/getting-started/errors-and-billing/index.mdx