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

# Error Handling

> Learn how the CCCAMBOX TV Reseller API reports errors, which status codes to expect, and how to handle error responses correctly.

The API uses standard HTTP status codes to indicate whether a request
succeeded or failed.

* `2xx` indicates a successful request
* `4xx` indicates a client-side problem such as invalid input, missing
  authentication, or an action that cannot be performed
* `5xx` indicates an unexpected server-side failure

## Error categories

Errors generally fall into two groups:

* **Client errors**: the request must be corrected before retrying
* **Server errors**: the request may be valid, but the API failed while handling it

### Client errors

Client errors return a `4xx` status code. These usually mean one of the
following:

* The request body or query parameters are invalid
* Authentication is missing or invalid
* The requested resource does not exist
* The requested action is not allowed in the current state
* Your account does not have enough balance to perform the action
* You have exceeded the rate limit

For client errors, correct the request before retrying.

### Server errors

Server errors return a `5xx` status code. These indicate that the API failed
while processing an otherwise valid request.

When you receive a server error:

* Treat the result as indeterminate
* Retry only when it is safe for your use case
* Capture the `x-request-id` response header
* Include the request ID if you contact support

## Error response format

Error responses are returned as JSON. In most cases, you can expect at least a
stable `code` field and a human-readable `message` field.

The examples below show a typical authentication error, a validation error, and
a server-side failure:

<CodeGroup>
  ```json 400 theme={null}
  {
    "code": "request_errors",
    "message": "Request error occurred.",
    "data": {
      "errors": [
        {
          "code": "invalid_type",
          "message": "Expected string, received number",
          "path": ["label"]
        }
      ]
    }
  }
  ```

  ```json 401 theme={null}
  {
    "code": "not_authorized",
    "message": "Not authorized to perform this action."
  }
  ```

  ```json 500 theme={null}
  {
    "code": "server_error",
    "message": "Internal server error occurred.",
    "requestId": "6f3b3d9f-4c47-4fd7-8a53-0d7f0f4e6abc"
  }
  ```
</CodeGroup>

Depending on the failure type, the response may include additional details:

* Validation errors can include a structured `data.errors` array with field-level
  information such as the invalid path, the validation code, and a specific
  message.
* Malformed JSON may return a simpler `400` response with only `code` and
  `message`.
* Server errors can include a `requestId` field in the response body so you can
  correlate the failure with logs or share it with support.

## Common status codes

| HTTP Status Code            | Meaning                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | The request could not be processed because parameters, query values, or the JSON body were invalid. |
| `401 Unauthorized`          | The API key is missing, invalid, disabled, or not authorized for the request.                       |
| `402 Payment Required`      | The action requires more balance than is currently available on the account.                        |
| `404 Not Found`             | The requested resource could not be found.                                                          |
| `406 Not Acceptable`        | The requested action is not compatible with the target resource or selected duration.               |
| `409 Conflict`              | The request conflicts with existing data, such as a username or MAC address that already exists.    |
| `429 Too Many Requests`     | The rate limit has been exceeded. Retry with backoff.                                               |
| `500 Internal Server Error` | An unexpected server-side error occurred.                                                           |

## Common error codes

The API may return error codes such as:

* `request_errors`
* `not_authorized`
* `insufficient_balance`
* `member_not_found`
* `api_key_not_found`
* `api_key_disabled`
* `username_already_exist`
* `macaddress_already_exist`
* `line_not_authorized`
* `line_not_found`
* `unavailable_duration`
* `rate_limit`
* `server_error`

Handle the `code` field programmatically when you need stable application logic,
and use the `message` field for human-readable debugging information.