Errores y administración
Cómo interpretar errores, cuándo reintentar, cuándo detenerte y qué controles administrativos existen para tu cuenta API.
Formato de error
Todas las respuestas fallidas siguen el mismo envelope:
{
"success": false,
"requestId": "req_01K5CBM7N6V5C4X3Z2A1S0D9F8",
"timestamp": "2026-03-19T16:40:42.123Z",
"error": {
"code": "INVALID_API_KEY",
"message": "La API key no es válida.",
"details": null
}
}Códigos frecuentes
| Código | Qué significa | Acción recomendada |
|---|---|---|
MISSING_API_KEY | No enviaste API key | Corrige el header |
INVALID_API_KEY | La API key no es válida | Regenera o revisa credenciales |
INVALID_SOURCE_IP | La IP no está autorizada | Revisa IPs registradas |
IP_LIMIT_REACHED | Ya agotaste las 5 IPs permitidas | Elimina IPs viejas desde el panel |
RATE_LIMITED | Excediste tus límites | Espera y reintenta con control |
SERVICE_NOT_FOUND | El servicio no existe | Revisa serviceId |
SERVICE_UNAVAILABLE | El servicio no está ordenable | Refresca catálogo o detén venta |
INVALID_INPUTS | Faltan o sobran campos | Revisa el inputSchema |
ORDER_NOT_FOUND | El pedido no existe para esa cuenta | Revisa orderId |
IDEMPOTENCY_KEY_REUSED | Reusaste la llave con otro payload | Genera una nueva llave |
INTERNAL_ERROR | Error interno o aguas arriba | Guarda requestId y reintenta según caso |
Cómo decidir si debes reintentar
No reintentes automáticamente
No reintentes si el problema es:
- autenticación;
- permisos;
serviceIdinválido;- inputs inválidos;
- idempotencia mal usada.
Sí puedes reintentar con control
Puedes reintentar si el problema es claramente transitorio, por ejemplo:
- timeout de red;
- error temporal del upstream;
429 RATE_LIMITEDdespués de esperar.
En esos casos:
- reutiliza la misma
Idempotency-Keysi es exactamente el mismo pedido; - registra el
requestId; - evita reenviar múltiples veces en paralelo.
Qué puede gestionar CelMex a nivel cuenta API
Desde CelMex se puede gestionar por cuenta API:
- activación o suspensión de acceso;
- regeneración de la API key;
- revisión de IPs registradas;
- límites operativos;
- actividad reciente.
Qué debes guardar para soporte
Cuando reportes un problema, intenta guardar al menos:
requestId- tu referencia interna
- el endpoint llamado
- la fecha y hora aproximada
- el payload enviado
- la respuesta completa
Recomendación operativa
La forma más segura de operar es:
- validar servicio y detalle antes de vender;
- usar idempotencia siempre en creación;
- guardar
requestIden todos los logs; - tratar autenticación y validación como errores finales;
- tratar errores temporales con reintento controlado, no agresivo.