Interpretar errores y reintentar sin duplicar
Los dos formatos de error, qué significa cada código HTTP y cuándo es seguro repetir una petición.
En esta página4 secciones
Formatos de error
La autenticación y las funciones (crear…, pagar…, exportar…) responden {"status": "error", "message": "…"}.
Los recursos de datos responden {"error": "…"} y pueden añadir data con el registro afectado. Lee message o error, según exista.
{
"status": "error",
"message": "codcliente field is required"
}{
"error": "Registro no encontrado"
}Códigos HTTP
Códigos
-
400Datos - «Registro duplicado», «Ningún dato recibido por formulario», «Ha ocurrido un error mientras se guardaban los datos - …»,
… field is required. Corrige el dato; no repitas igual. -
401Clave - «Clave de API no válida». Revisa la cabecera y que la clave siga activa.
-
403Permiso - La clave no tiene ese recurso o método.
-
404No existe - «Registro no encontrado», recurso mal escrito,
customer-not-found. -
405Método method-not-allowed: las funcionescrear…van con POST;exportar…, con GET.-
409API - «API desactivada. Puede activarla desde el panel de control».
-
422Negocio - «Ha ocurrido un error mientras se guardaban los datos» o un error en el cálculo de totales: el programa rechazó el documento y no se creó nada.
-
429Bloqueo - Cinco fallos de clave o permiso en 10 minutos: la IP queda bloqueada 10 minutos.
-
500Interno API-ERROR: …u otro error interno. Comprueba que no se creó nada y repite una sola vez.
Reintentar sin duplicar
Errores de datos (400, 404, 422) y de configuración (401, 403, 409): corrige la causa; repetir la misma petición dará el mismo error.
Tiempo de espera o red cortada en un POST: la operación pudo completarse. Busca el registro con un filtro (cliente, fecha, tu referencia) y repite solo si no existe.
Se pueden repetir sin crear nada nuevo: PUT y DELETE sobre un registro concreto de un recurso de datos (/api/3/{recurso}/{id}) y pagarFactura… sobre la misma factura.
El método no basta para saber si es seguro repetir: las funciones crear… y crearFacturaRectificativaCliente admiten también PUT y crean un documento nuevo en cada llamada. Antes de repetirlas, comprueba si el documento ya existe.
Fechas: envíalas como dd-mm-aaaa; las respuestas las devuelven igual.
Si sigue fallando
Escribe a soporte con el método, la URL sin la clave, el código HTTP, el cuerpo de la respuesta y la hora. Nunca envíes la clave.