# Error semantics

:::danger[The #1 integration surprise]

The Apaczka API v2 returns **HTTP status 200 for every response —
including errors**. Never use the HTTP status code to detect failure.

:::

## The response envelope

Every response is JSON in a universal envelope:

```json
{
  "status": 200,
  "message": "",
  "response": { "...": "..." }
}
```

| Field | Meaning |
|---|---|
| `status` | The **real** outcome: `200` = success, anything else = error code |
| `message` | Human-readable error description (empty on success) |
| `response` | Method-specific result; `null` on failure |

## A failed call

```json
{
  "status": 400,
  "message": "Invalid signature",
  "response": null
}
```

Your client must check `status` in the **body** of every response:

```php
$body = json_decode($response->getBody(), true);

if (($body['status'] ?? 0) !== 200) {
    throw new ApiException($body['message'] ?? 'Unknown error', $body['status']);
}

return $body['response'];
```

{/* TODO(wave-1): enumerate known status codes and messages per method. */}