Primeros pasos
Errores
Formato de los errores, códigos de estado y cuándo conviene reintentar.
La API usa los códigos de estado HTTP habituales. Cuando algo falla, el cuerpo es un JSON con error (un mensaje en español) y, si el problema está en los datos enviados, details: una lista con una línea por campo, en la forma campo: motivo.
1{2 "error": "Datos inválidos",3 "details": [4 "limit: Too big: expected number to be <=200"5 ]6}Códigos de estado#
| Código | Significado | Ejemplos de error | ¿Reintentar? |
|---|---|---|---|
Código200 / 201 | SignificadoCorrecto. 201 cuando se creó algo. | Ejemplos de error— | ¿Reintentar?— |
Código400 | SignificadoLos datos enviados no son válidos o rompen una regla. | Ejemplos de errorDatos inválidos, Token no soportado. Usa: USDT, USDC, Configura primero webhook_url | ¿Reintentar?No. Corrige la petición. |
Código401 | SignificadoFalta la clave, es incorrecta o está revocada. | Ejemplos de errorClave de API inválida, No autorizado | ¿Reintentar?No. Revisa la clave. |
Código404 | SignificadoEl recurso no existe o no es de tu empresa. | Ejemplos de errorUsuario no encontrado, Depósito no encontrado, Evento no encontrado, Clave no encontrada | ¿Reintentar?No. |
Código409 | SignificadoLa operación choca con el estado actual. | Ejemplos de errorEs la única clave activa: crea otra antes de revocar esta | ¿Reintentar?No, hasta resolver el conflicto. |
Código413 | SignificadoEl cuerpo supera 64 KB. | Ejemplos de errorMensaje del servidor web | ¿Reintentar?No. Envía menos datos. |
Código500 | SignificadoFallo del servidor o de la red blockchain. | Ejemplos de errorError interno | ¿Reintentar?Sí, con espera creciente. |
- Los mensajes de
detailslos genera el validador y están en inglés (Invalid UUID,Too big: …). Úsalos para depurar, no para mostrarlos al usuario ni para tomar decisiones en el código. - Decide por el código de estado, no por el texto de
error: los textos pueden cambiar. - Un recurso de otra empresa responde
404, igual que uno que no existe. - Una ruta que no existe responde
404con el formato del servidor web:{ "message": "Route GET:/x not found", "error": "Not Found", "statusCode": 404 }.
Cómo reintentar#
Reintenta solo los 500 y los fallos de conexión, esperando cada vez más (por ejemplo 1 s, 2 s, 4 s, hasta 30 s). Las rutas que cambian condiciones (PATCH /v1/me) escriben primero en la blockchain: si responden 500, no cambió nada y se pueden repetir. Qué rutas se pueden repetir sin riesgo está en Peticiones repetidas. Anota siempre el id de petición.
Aún no hay límite de peticiones
La API todavía no devuelve 429. Está previsto un límite por clave, así que conviene tratar un 429 futuro como reintentable. Ver Límites.