Referencia de códigos de error
Comprende los códigos de estado HTTP y cómo manejarlos
2xx Éxito
La solicitud fue exitosa y la respuesta contiene los datos solicitados.
Común con: solicitudes GET, POST, PUT
Se creó exitosamente un nuevo recurso.
Común con: solicitudes POST para crear recursos
4xx Errores del cliente
La solicitud estaba mal formada o contiene parámetros inválidos.
Causas comunes: campos requeridos faltantes, JSON inválido, tipos de datos incorrectos
Se requiere autenticación o ha fallado. Tu clave API puede estar faltando o ser inválida.
Causas comunes: clave API faltante, clave API inválida, clave expirada
No tienes permiso para acceder a este recurso. Tu clave API puede carecer de los permisos requeridos.
Causas comunes: permisos insuficientes, cuenta suspendida, acceso a endpoint de prueba con clave de producción
El recurso solicitado no existe. Verifica la URL de tu endpoint.
Causas comunes: URL incorrecta, error tipográfico en la ruta del endpoint, recurso eliminado
La solicitud estaba bien formada pero contiene errores semánticos o fallas de validación.
Causas comunes: formato de correo inválido, valores fuera de rango, fallas de validación de lógica de negocio
Has superado tu límite de tasa. Espera antes de hacer más solicitudes o actualiza tu plan.
Causas comunes: demasiadas solicitudes por minuto, cuota diaria superada
5xx Errores del servidor
Ocurrió un error inesperado en nuestros servidores. Es un problema temporal.
Acción: Reintenta la solicitud. Si el problema persiste, contacta al soporte.
La puerta de enlace recibió una respuesta inválida del servidor backend.
Acción: Reintenta la solicitud después de una breve pausa.
El servicio no está disponible temporalmente, generalmente por mantenimiento o sobrecarga.
Acción: Verifica nuestra página de estado y reintenta después de una pausa.
La puerta de enlace no recibió respuesta del servidor backend a tiempo.
Acción: Reintenta la solicitud. Considera implementar retroceso exponencial.
Mejores prácticas para el manejo de errores
- ✓ Siempre verifica el código de estado antes de procesar la respuesta
- ✓ Implementa retroceso exponencial para la lógica de reintento en errores 5xx
- ✓ Registra detalles de errores para depuración pero nunca expongas datos sensibles
- ✓ Maneja los límites de tasa con elegancia respetando los encabezados retry-after
- ✓ Muestra mensajes de error amigables para el usuario en lugar de respuestas API sin procesar
¿Necesitas ayuda para solucionar problemas?