El envelope de respuesta y cómo manejar errores

Cada respuesta de la API de Arko, sin excepción, llega envuelta en la misma forma: success y data cuando todo salió bien, success en false, message y cause cuando no. Diseñar tu manejo de errores alrededor de ese contrato único, en vez de inspeccionar el código HTTP caso por caso, es lo que hace que tu integración aguante el día que algo falla de una forma que no anticipaste.

Lo que trae un error

El código dentro de cause es el valor sobre el que conviene ramificar tu lógica: cadenas como ERR_NO_TOKEN, ERR_QUOTA_EXCEEDED o ERR_NOT_FOUND te dicen exactamente qué pasó, de una forma que no cambia aunque el texto de message se ajuste con el tiempo. El identificador que lo acompaña sirve para reportar ese error puntual si hace falta. En producción, los errores 5xx y los mensajes técnicos se enmascaran con textos genéricos, así que no construyas lógica sobre el contenido exacto de message.

Tres familias de error que vas a ver seguido

• Autenticación: sin credencial, con un JWT inválido, o con una key vencida.
• Permisos: tu key no tiene el scope que exige el endpoint, o intenta uno reservado a JWT.
• Límites: tu cuenta agotó lo que su plan permite, ya sea por cuota de uso o por tope de recurso.

No toda petición mal formada es igual

Un content type incorrecto en un POST responde con un error 415; un cuerpo que no es JSON válido responde con un 400. Son errores de forma, previos a cualquier validación de negocio, y se resuelven revisando cómo construyes la petición, no reintentando.

Reintentar con criterio, no por costumbre

Un error de autenticación o de validación no se arregla reintentando: la petición va a fallar exactamente igual la segunda vez. Reserva el reintento —con espera creciente— para lo que de verdad es transitorio: un error de red, un 5xx puntual. Ramificar por el código de cause es lo que te permite tomar esa decisión de forma automática en vez de adivinar.