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

# Error Handling

> Reference for OpenCard HTTP status codes, validation errors, webhook delivery retries, and common integration gotchas when building on the EMS API.

## API errors

| Code  | Meaning                  | Fix                                              |
| ----- | ------------------------ | ------------------------------------------------ |
| `400` | Bad request / validation | Check field formats (org numbers, country codes) |
| `401` | Invalid token            | Refresh OAuth token                              |
| `403` | Missing scope            | Add scope to OAuth client                        |
| `404` | Not found                | Check IDs, or no access                          |
| `409` | Conflict                 | Duplicate (e.g. issuer transaction state ID)     |
| `422` | Business rule            | e.g. delete signed signatory                     |

***

## Webhook delivery

* OpenCard retries failed deliveries
* Check delivery log: `GET .../webhooks/{id}/events`
* Your endpoint must return `200` fast
* Process heavy work async (queue it)

***

## Common gotchas

| Issue                                 | Cause                              | Fix                                               |
| ------------------------------------- | ---------------------------------- | ------------------------------------------------- |
| HTML login page instead of JSON error | Missing `Accept: application/json` | Send `Accept: application/json` on every API call |
| Webhook `active=false`                | Challenge failed                   | Implement HMAC challenge handler                  |
| No transactions                       | TPA not activated                  | Wait for issuer card confirmation                 |
| No transactions                       | PDPC not signed                    | Cardholder must sign consent                      |
| Duplicate txs                         | Same transaction received twice    | Upsert by transaction `id`                        |
| Wrong VAT on tx                       | Network VAT, not merchant          | Subscribe to `transaction.true.vat`               |