Errors de l'API i què signifiquen
Què acostuma a significar cada estat HTTP de l'API de Didit a la pràctica: 401 i 403 relacionats amb claus i permisos, problemes de saldo similars a un 402, límits de velocitat 429, i com llegir el cos de l'error.
Llegeix el cos de la resposta. Els errors de Didit porten un missatge i sovint un codi de detall que indica el problema real - l'estat per si sol gairebé mai n'hi ha prou. El 401 és la clau, el 403 és de permisos o d'entorn, i el 429 és de límit de velocitat, mentre que un error de saldo és de crèdits, no de codi.
#Llegeix primer el cos
L'estat HTTP indica la categoria. El cos indica què ha passat. Gairebé totes les hores de depuració evitables en una integració amb l'API es dediquen a intentar endevinar un codi d'estat quan la resposta era en un cos que s'ha descartat.
- Una clau desactivada o d'una aplicació incorrecta és la causa habitual d'un 401.
- Last used confirma si la clau que creus que estàs enviant és realment la que arriba.
- Rota el secret si una clau pot haver-se filtrat - un 401 és millor que una fuita de dades.
Registra el cos complet de l'error - estat, capçaleres i payload - en cada trucada fallida, en cada entorn. El necessitaràs, i és molt més difícil de reconstruir més endavant.
#Què acostuma a significar cada estat
| Estat | Causa habitual |
|---|---|
| 400 | Una sol·licitud mal formada - un camp obligatori que falta, un valor d'enum incorrecte, un objecte niat amb la forma equivocada |
| 401 | L'autenticació ha fallat. La capçalera x-api-key falta, està mal formada o no és una clau vàlida |
| 403 | Autenticat però no permès. Entorn equivocat, un permís que la teva clau no té, o una funcionalitat no activada al teu compte |
| 404 | El recurs no existeix - o existeix sota una aplicació diferent de la de la clau que has fet servir |
| 409 | Un conflicte amb l'estat existent, com ara una acció que ja s'ha fet |
| 422 | La sol·licitud estava ben formada però els valors no són acceptables - és un error de validació, no de sintaxi |
| 429 | Límit de velocitat. Vegeu més avall |
| 5xx | Un problema del costat de Didit. Reintenta amb backoff i consulta status.didit.me |
#401 vs 403 - la distinció que estalvia temps
401 vol dir que la clau no s'ha acceptat en absolut. Comprova que estàs enviant x-api-key, que el valor no té espais en blanc ni cometes de més, i que no has enganxat un secret de signatura de webhook en lloc de la clau d'API - són coses diferents i és un error habitual.
403 vol dir que la clau és vàlida però aquesta crida no està permesa. Tres causes, per ordre:
- Discrepància d'entorn. Els camps exclusius de sandbox (com
sandbox_scenario) es rebutgen en una aplicació en producció, i viceversa. Producció i sandbox són aplicacions separades amb claus separades. - Falta un permís. Algunes operacions necessiten permisos que la teva clau o el teu rol no tenen. Si necessites permisos de creació i gestió de sessions que no tens, això és una petició per a suport, no un arranjament de codi.
- Funcionalitat no activada. Algunes capacitats es proveeixen per organització. Un 403 en una funcionalitat que creus que hauries de tenir val la pena preguntar-lo abans de reescriure la crida.
No hi ha cap manera integrada de distingir una clau de sandbox d'una de producció només mirant-la, així que guarda-les amb noms clarament diferenciats al teu gestor de secrets i no deixis mai que una única variable d'entorn contingui "la clau que toqui en cada moment". Una clau de producció en un entorn de proves gasta crèdits reals.
#Un 404 que hauria d'existir
Si una sessió o un flux de treball retorna 404 i estàs segur que existeix, la resposta habitual és que existeix sota una aplicació diferent de la de la clau amb què t'has autenticat. Els recursos estan delimitats per la seva aplicació; una clau de l'aplicació A no pot veure les sessions de l'aplicació B.
#Errors de saldo i crèdit
Una crida que falla perquè no hi ha prou crèdits no és un problema de codi. El flux de treball conté una funcionalitat de pagament i el teu saldo no la cobreix. Aquest és, de llarg, el report de "l'API s'ha trencat" més habitual, i la causa gairebé sempre és marca blanca, AML o NFC en un flux de treball que s'esperava que fos gratuït. Vegeu com solucionar un error de "no hi ha prou crèdits".
#Límit de velocitat 429
Els límits s'apliquen per identificador - la teva x-api-key, o la teva IP de client si no s'envia cap clau - amb un comptador independent per àmbit en una finestra lliscant de 60 segons.
Valors globals per defecte:
| Àmbit | Mètodes | Límit |
|---|---|---|
| Lectures genèriques | GET | 600 / min |
| Escriptures genèriques | POST, PATCH, DELETE | 300 / min |
Alguns endpoints d'alt impacte tenen límits més estrictes a més del global, i el primer àmbit que supera el seu comptador és el que retorna 429. Taula completa: límit de velocitat.
Gestiona el 429 amb backoff exponencial i jitter. Un bucle de reintents massa freqüent contra un límit de velocitat empitjora el problema i pot mantenir-te limitat indefinidament.
Els processos per lots solen ser l'origen habitual d'un 429 - una importació nocturna que llança centenars de creacions en pocs segons. Reparteix la feina en lloc d'augmentar la concurrència fins que deixi de donar error.
#Codis de detall a nivell de funcionalitat
Més enllà dels estats HTTP, cada comprovació individual retorna els seus propis codis de detall per a problemes a nivell de proveïdor - per exemple, una integració de registre que no té accés a un producte concret en un país concret. Quan en rebis un, el codi indica exactament la situació, així que cita'l literalment quan preguntis sobre ell.
Si una resposta omet un codi de detall que esperaves trobar al catàleg, val la pena reportar-ho en lloc de buscar-hi una solució alternativa - un codi que falta és una llacuna real, i fa que el mateix problema sigui més difícil per a la següent persona.
#Les respostes buides no són un èxit
Una comprovació basada en un proveïdor que retorna un cos buit no és el mateix que un resultat net. Tracta "sense dades" com un cas propi al teu codi en lloc de mapejar-lo com un resultat aprovat - especialment en validació de bases de dades i cribratge de carteres, on un servei no proveït i un no-match genuí es poden semblar des de fora.
#Provar els camins d'error
El sandbox força fallades concretes de manera determinista, que és l'única manera raonable de provar la teva gestió d'errors. Vegeu com provar en sandbox.