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

# Handling Errors

> HTTP response codes and error format for the Qonversion REST API v4

The v4 API uses the same HTTP status codes and error envelope as v3.

## HTTP Response Codes

| Code | State                | Description                                                       |
| ---- | -------------------- | ----------------------------------------------------------------- |
| 200  | Success              | Everything worked as expected                                     |
| 201  | Created              | Operation led to creation of a resource                           |
| 204  | No Content           | Server fulfilled request, no content in response body             |
| 400  | Bad Request          | Request not accepted, often due to missing required parameter     |
| 401  | Unauthorized         | Invalid API key provided                                          |
| 403  | Forbidden            | Authorization by a Secret Key required                            |
| 404  | Not Found            | Requested resource does not exist                                 |
| 409  | Conflict             | Resource already exists or operation conflicts with current state |
| 422  | Unprocessable Entity | Cannot process request due to logical error                       |
| 429  | Too Many Requests    | Rate limit exceeded                                               |
| 5xx  | Server Errors        | Something went wrong on Qonversion's end (rare)                   |

## Error Response Format

All v4 errors follow a single envelope keyed under `error`. There is no envelope-level `meta` (or `_meta`) key — validation field errors live inside `error.details` as `{field, message}` pairs:

```json theme={null}
{
  "error": {
    "type": "request",
    "code": "invalid_data",
    "message": "Validation failed",
    "details": [
      { "field": "short_name", "message": "Value is too long" },
      { "field": "last_name", "message": "Required" }
    ]
  }
}
```

`error.details` is omitted entirely (rather than emitted as `null` or `[]`) when the failure is not field-scoped — for example, a 401 unauthorized or a 404 resource-not-found returns just `{type, code, message}`.

## Error Types

| Type       | Description                                                                           |
| ---------- | ------------------------------------------------------------------------------------- |
| `request`  | Error in request validation (not enough data, invalid data, auth required)            |
| `resource` | Request is valid but the action could not be executed                                 |
| `logical`  | Client can execute action but there is an error in communicating with the application |
| `internal` | All request handling stages succeeded but an internal error occurred                  |

## Error Codes

### Request Errors

| Code                   | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `invalid_data`         | Validation failed. See `error.details` for the failing fields. |
| `invalid_request`      | Unrecognized request URL                                       |
| `control_unauthorized` | Authorization required                                         |
| `control_forbidden`    | Authenticated but not allowed (wrong key type or scope)        |
| `not_implemented`      | Functionality at the requested address is not implemented      |
| `rate_limited`         | Too many requests — back off and retry                         |

### Resource Errors

| Code             | Description                                           |
| ---------------- | ----------------------------------------------------- |
| `not_found`      | Requested resource not found                          |
| `already_exists` | Requested resource already exists                     |
| `conflict`       | Resource state conflicts with the requested operation |

### Logical Errors

| Code                 | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `purchase_fraud`     | Could not validate purchase with store, potential fraud |
| `relation_not_found` | Nested objects could not be found or associated         |

### Internal Errors

| Code            | Description                          |
| --------------- | ------------------------------------ |
| `storage_error` | Data was not saved                   |
| `network_error` | Internal services interaction failed |
| `unknown_error` | Unknown reason                       |