# Errors

Public API failures use an HTTP status and a JSON envelope:

```json
{
  "success": false,
  "error": "Human-readable error message"
}
```

## Status guide

| Status | Meaning | Recommended handling |
| --- | --- | --- |
| `400 Bad Request` | The request or connection token is invalid. | Correct the request. Do not retry unchanged input. |
| `401 Unauthorized` | API credentials are missing or invalid. | Check both authentication headers. |
| `403 Forbidden` | Provider type or permission does not allow the operation. | Use the correct credential or update its permission. |
| `409 Conflict` | The requested connection conflicts with existing state. | Treat as a business result and inspect the message. |
| `500 Internal Server Error` | Onward could not complete the operation. | Retry with bounded exponential backoff and preserve your correlation context. |

## Retry policy

Retry only infrastructure and transient server failures. Use exponential backoff with jitter and a maximum number of attempts. Do not automatically retry validation, authentication, authorization, or conflict responses.

## Empty data is not an error

[`GET /v1/quest-chains/active/{platformUserId}`](/docs/api-reference/quest-chain-api#get-active-quest-chains-for-the-user) returns `200 OK` when no active chain exists. Inspect `user.exists` to distinguish an unknown user from a known user who currently has no active quest chains.

The [API Reference](/docs/api-reference) lists the responses currently declared for each operation and remains the source of truth for the public contract.