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

# Errors de l'API de Didit: codis, cossos i solucions

> Errors de l'API de Didit: codis HTTP, cossos de resposta, codis d'error estables i reintents segurs. Inclou 401, 403, 409, 429 i 5xx.

L'API de Didit indica un error amb un codi d'estat HTTP i, en gairebé tots els casos, amb un cos en JSON.
Aquesta pàgina enumera el significat de cada estat, l'aspecte del cos, els valors de `code` pels quals pots decidir una acció i els errors que es poden reintentar sense risc.
Fia't primer de l'estat i, si hi és, de `code`, perquè el text d'un missatge pot canviar.

## Codis d'estat

| Codi HTTP | Què significa | Què has de fer | Reintentar? |
| - | - | - | - |
| `400` | La sol·licitud no és vàlida: un camp no ha superat la validació, o no s'ha pogut llegir una imatge o un document | Corregeix el que indica el cos | Després de corregir-ho |
| `401` | La clau que has enviat és incorrecta, mal formada, revocada o caducada | Revisa `DIDIT_API_KEY` o crea una clau nova | Després de corregir-ho |
| `402` | No s'ha pogut cobrar la comprovació, per això no s'ha executat | Recarrega el saldo | Després de recarregar |
| `403` | No s'ha enviat cap clau, la clau no té accés a aquest recurs o acció, la sol·licitud arriba des de fora de la llista d'adreces IP de la clau, o el saldo no cobreix la crida | Llegeix el cos i consulta [Errors de clau d'API](#errors-de-clau-d’api) i [Crèdits insuficients](#crèdits-insuficients) | Després de corregir-ho |
| `404` | El recurs no existeix, o una sessió queda fora dels fluxos o estats de la clau | Revisa l'identificador i els límits de la clau | No |
| `409` | La sol·licitud entra en conflicte amb l'estat actual, per exemple un `Idempotency-Key` reutilitzat o un pas que ja s'ha executat | Llegeix `code` i torna a carregar l'estat | Depèn de `code` |
| `410` | El recurs ha caducat, per exemple una sessió o una invitació | Crea'n un de nou | No |
| `415` | El cos de la sol·licitud no és JSON | Envia `Content-Type: application/json` | Després de corregir-ho |
| `422` | Una adreça de cartera encaixa amb més d'una blockchain, per això no s'ha fet cap cribratge ni s'ha facturat res | Torna a enviar-la amb `blockchain` definit com un dels valors de `candidate_chains` | Després de corregir-ho |
| `429` | S'ha assolit un límit de freqüència o una quota | Espera el temps indicat per `Retry-After`; consulta [Límit de freqüència](https://docs.didit.me/ca/integration/rate-limiting.md) | Sí, després d'esperar |
| `500` | Un error inesperat per part de Didit | Reintenta amb retard progressiu i contacta amb suport si continua | Consulta [Reintents](#reintents-i-idempotència) |
| `502` | Un servei del qual depèn Didit ha retornat un error | Llegeix `code` | Consulta [Reintents](#reintents-i-idempotència) |
| `503` | Un servei del qual depèn Didit no està disponible temporalment | Llegeix `code` i torna-ho a intentar | Consulta [Reintents](#reintents-i-idempotència) |

## Cossos d'error

Els cossos d'error no comparteixen un mateix format, així que llegeix-los de manera defensiva.
La forma depèn de la família d'endpoints:

| Forma | On la veus | Exemple |
| - | - | - |
| `detail` | La majoria d'errors, inclosa l'autenticació, la indicació que no s'ha trobat el recurs i els límits de freqüència | `{"detail": "You do not have permission to perform this action."}` |
| `detail` i `code` | Errors amb un codi estable | `{"detail": "This application was deleted.", "code": "application_deleted"}` |
| Errors de camp | Validació d'entrada | `{"workflow_id": ["This field is required."]}` |
| `non_field_errors` | Validació entre diversos camps | `{"non_field_errors": ["..."]}` |
| Un array JSON | Alguns errors de validació, com una crida de simulació | `["Scenario can only be armed before the verification starts."]` |
| `error` | La majoria d'APIs independents | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `error` i `code` | Errors d'imatge en APIs independents | `{"error": "...", "code": "invalid_image"}` |
| `error` com a codi, amb `detail` | Verificació amb cartera d'identitat digital | `{"error": "insufficient_credits", "detail": "..."}` |

Un `500` pot no tenir cap cos JSON, així que gestiona un cos que no es pot analitzar.

```javascript theme={null}
const raw = await response.text();
let body = {};
try {
  body = JSON.parse(raw);
} catch {
  // A 5xx response may not be JSON: rely on response.status.
}
const code = body.code ?? null;
const message = body.detail ?? body.error ?? (Array.isArray(body) ? body[0] : raw);
```

## Errors de clau d'API

| Què has enviat | Estat | `detail` |
| - | - | - |
| Cap capçalera `x-api-key` | `403` | `You do not have permission to perform this action.` |
| Una clau incorrecta, mal formada o revocada | `401` | `Authentication credentials were not provided or are invalid.` |
| Una clau caducada | `401` | `This API key has expired.` |
| Una clau utilitzada des de fora de la seva llista d'adreces IP | `403` | `This API key can't be used from this IP address.` |
| Una clau amb permisos limitats i sense accés a aquest recurs o acció | `403` | `This API key has no access to this endpoint.` |
| Una clau limitada a alguns fluxos o estats, en un endpoint que no pot utilitzar | `403` | `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.` |
| Una clau limitada a alguns fluxos o estats, en una sessió fora d'aquests límits | `404` | `Session not found.` |
| Una clau l'aplicació de la qual s'acaba d'eliminar | `403` | `This application was deleted.`, amb `"code": "application_deleted"` |

Durant uns minuts després d'eliminar una aplicació, l'API respon amb `application_deleted`, i després rebutja la clau com qualsevol clau incorrecta.
No reintentis: l'aplicació i les seves claus ja no existeixen.

Consulta [Autenticació de l'API](https://docs.didit.me/ca/getting-started/api-authentication.md) i [Claus d'API](https://docs.didit.me/ca/console/api-keys.md) per saber com funcionen les claus i els seus límits.

## Crèdits insuficients

Cada família d'APIs informa d'un saldo baix de manera diferent:

| Crida | Estat | Cos |
| - | - | - |
| `POST /v3/session/` | `400` | `{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| La majoria d'APIs independents | `403` | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `POST /v3/bank/account-check/` | `402` | `{"detail": "...", "code": "insufficient_credits"}` |
| Verificació amb cartera d'identitat digital | `403` | `{"error": "insufficient_credits", "detail": "..."}` |
| Transaccions, Travel Rule i validació d'adreces | `403` | `{"detail": "...", "code": "insufficient_credits"}` |

En un contracte, la creació de sessió respon amb `403` i `"code": "contract_billing_suspended"` mentre els serveis de pagament estiguin suspesos per a la teva organització.
Les [aplicacions de sandbox](https://docs.didit.me/ca/integration/sandbox-testing.md) mai es facturen, així que no fan aquestes comprovacions.

## Codis d'error

Aquests valors de `code` són estables, així que pots basar-hi la lògica del codi. La majoria apareixen al costat de `detail`; a la verificació amb carteres d'identitat digital, el codi és el valor de `error`.

### Accés i facturació

| Codi | Estat | Significat |
| - | - | - |
| `insufficient_credits` | `402`, `403` | El saldo no cobreix la crida |
| `contract_billing_suspended` | `403` | Els serveis de pagament estan pausats per a aquesta organització |
| `contract_rate_missing` | `402`, `403` | El contracte no té tarifa per a aquesta comprovació |
| `application_deleted` | `403` | L'aplicació de la clau s'ha eliminat |
| `organization_deleted` | `403` | L'organització de la clau s'ha eliminat |
| `event_monitoring_disabled` | `403` | La ingestió d'esdeveniments no està activada per a aquesta aplicació |
| `networks_not_entitled` | `403` | Les xarxes de frau no estan habilitades per a aquesta organització |

### Sol·licituds i idempotència

| Codi | Estat | Significat |
| - | - | - |
| `invalid_image` | `400` | No s'ha pogut utilitzar la imatge |
| `return_url_invalid` | `400` | La URL de retorn no està permesa |
| `idempotency_key_invalid` | `400` | La `Idempotency-Key` té més de 255 caràcters |
| `idempotency_key_reused` | `409` | La clau ja s'ha utilitzat amb un cos diferent |
| `idempotency_key_in_progress` | `409` | La primera sol·licitud amb aquesta clau encara s'està executant; espera el valor de `Retry-After` |
| `verification_in_progress` | `409` | L'usuari està completant aquesta verificació en aquest moment, així que no es pot cancel·lar; espera el valor de `Retry-After` |
| `feature_override_not_pending` | `409` | La modificació ja s'ha aplicat o s'ha cancel·lat |

### Comprovacions bancàries, de telèfon i de risc

| Codi | Estat | Significat |
| - | - | - |
| `invalid_account_input` | `400` | Les dades del compte no són vàlides |
| `country_not_covered` | `404` | La comprovació no cobreix aquest país ni aquest tipus de compte |
| `bank_not_covered` | `404` | La comprovació no arriba a aquest banc |
| `bank_verification_not_available` | `404` | La verificació bancària no està disponible |
| `account_check_unavailable` | `503` | La comprovació no està disponible temporalment i la sol·licitud no s'ha cobrat |
| `phone_provider_unavailable` | `502` | La verificació de telèfon no està disponible temporalment; no es factura res i no es consumeix cap intent |
| `risk_lookup_unavailable` | `502` | La consulta de risc no està disponible temporalment i la sol·licitud no s'ha cobrat |

### Verificació d'empreses (KYB)

| Codi | Estat | Significat |
| - | - | - |
| `kyb_registry_provider_unavailable` | `502` | El registre mercantil no està disponible temporalment |
| `kyb_registry_country_unsupported` | `400` | La cerca al registre no cobreix aquest país |
| `kyb_registry_search_limit_reached` | `429` | L'aplicació ha arribat al límit de 600 cerques de pagament per hora |
| `kyb_session_not_writable` | `409` | La sessió ha finalitzat |
| `kyb_step_mismatch` | `409` | La sessió es troba en un altre pas; `next_step` n'indica quin |
| `kyb_no_party_drafts` | `409` | No hi ha esborranys de parts per enviar |
| `kyb_parties_already_submitted` | `409` | Les parts ja s'han enviat |
| `kyb_party_kyc_session_not_deleted` | `409` | La verificació de la part encara està activa, així que no es pot regenerar |

### Carteres d'identitat digital

| Codi | Estat | Significat |
| - | - | - |
| `wallet_unavailable` | `403` | Aquesta cartera no està disponible per a la teva aplicació |
| `wallet_provider_unavailable` | `502` | La cartera no s'ha pogut iniciar i no s'ha creat res |
| `wallet_not_configured` | `503` | Aquest entorn no pot accedir a la cartera |

### Informes i casos

| Codi | Estat | Significat |
| - | - | - |
| `report_deletion_pending` | `409` | L'informe s'està eliminant; repeteix l'eliminació per acabar d'esborrar els seus fitxers |
| `report_storage_unavailable` | `503` | No s'han pogut esborrar els fitxers de l'informe; repeteix l'eliminació |
| `wallet_address_deletion_incomplete` | `503` | No s'ha pogut eliminar un fitxer emmagatzemat, així que l'eliminació s'ha aturat; torna-ho a provar |
| `case_request_not_waiting` | `409` | La sol·licitud ja no està pendent del client, així que no hi ha res a recordar-li |
| `case_request_reminder_too_soon` | `429` | Fa poc que s'ha enviat un recordatori; `retry_at` indica quan pots enviar el següent |

### Signatures electròniques

| Codi | Estat | Significat |
| - | - | - |
| `signature_not_found` | `404` | La signatura no existeix |
| `signature_field_not_found` | `404` | El camp de signatura no existeix |
| `signature_not_signed` | `404`, `409` | El document no s'ha signat |

En crear la sessió, els problemes del document següents arriben com a valor del camp que els origina, amb estat `400`, per exemple `{"sign": "signature_document_changed"}`:

| Valor | Significat |
| - | - |
| `signature_document_changed` | El document és diferent del que es va enviar primer |
| `signature_document_not_supported` | El format del document no és compatible |
| `signature_document_conversion_failed` | No s'ha pogut convertir el document |
| `field_anchor_not_found` | No s'ha trobat l'ancoratge de text del camp al document |
| `field_value_missing` | Un camp no té valor |

### Webhooks

| Codi | Estat | Significat |
| - | - | - |
| `webhook_url_missing` | `400` | El lliurament no té cap URL registrada, així que no s'envia res |
| `invalid_webhook_payload` | `400` | Les dades del webhook no tenen un format vàlid |
| `webhook_resend_error` | `400` | El lliurament emmagatzemat no s'ha pogut tornar a signar, o no s'ha pogut completar l'intent |

## Reintents i idempotència

Alguns errors es poden repetir amb seguretat i d’altres no:

* **`429`:** espera la capçalera `Retry-After` i, després, torna-ho a intentar.
* **`502` i `503`:** torna-ho a intentar amb retrocés quan la referència de l’endpoint indiqui que no s’ha facturat res, com passa amb les comprovacions de telèfon, correu electrònic, bancàries i de risc.
* **`502` en `POST /v3/database-validation/`:** llegeix primer cada entrada de `validation_errors`, perquè aquest estat per si sol no significa un error temporal.
* **`503` en una eliminació:** repeteix la mateixa sol·licitud fins que retorni `200`.
* **Altres `4xx`:** corregeix primer la sol·licitud, perquè la mateixa sol·licitud fallarà de la mateixa manera.

`POST /v3/aml/` i la verificació de cartera de Digital ID accepten una capçalera `Idempotency-Key` de fins a 255 caràcters.
Si repeteixes una sol·licitud amb la mateixa clau i el mateix cos, es reprodueix la resposta emmagatzemada, de manera que l’operació i el càrrec s’executen una sola vegada.
La mateixa clau amb un cos diferent respon amb `409`, i mentre la primera sol·licitud encara s’està executant, els endpoints de cartera responen amb `409` i `Retry-After`.

`POST /v3/session/` no té cap clau d’idempotència, així que, si una creació supera el temps d’espera, llista les sessions per `vendor_data` abans de crear-ne una altra.

## Relacionat

* [Límit de freqüència](https://docs.didit.me/ca/integration/rate-limiting.md): límits, capçaleres i el cos de la resposta `429`.
* [Autenticació de l’API](https://docs.didit.me/ca/getting-started/api-authentication.md): com enviar la teva clau.
* [Proves al sandbox](https://docs.didit.me/ca/integration/sandbox-testing.md): reprodueix els resultats sense dades reals ni facturació.
* [Webhooks](https://docs.didit.me/ca/integration/webhooks.md): lliurament, reintents i ordre.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.