Códigos de Error
Referencia completa de códigos de error HTTP y errores de la API de ReciGo.
Formato de Respuesta de Error
Todos los errores de la API siguen el mismo formato JSON:
{
"error": "error_code",
"message": "Descripción legible del error",
"details": {
"field1": "Descripción del problema en field1",
"field2": "Descripción del problema en field2"
}
}errorCódigo de error en formato snake_case. Útil para manejo programático.
messageDescripción legible del error en español. Puede mostrarse al usuario.
detailsObjeto opcional con detalles adicionales sobre campos específicos que causaron el error.
Códigos de Estado HTTP
La solicitud fue exitosa. Se usa para consultas GET.
Un recurso fue creado exitosamente. Se usa para solicitudes POST que crean trabajos.
Los datos de entrada son inválidos o están mal formateados.
{
"error": "validation_error",
"message": "Datos de entrada inválidos",
"details": {
"size": "Debe ser uno de: S, M, L, XL",
"pickup.address": "Dirección de recogida es requerida",
"customer_phone": "Formato de teléfono inválido"
}
}API key inválida, faltante o revocada.
{
"error": "unauthorized",
"message": "API key inválida o faltante"
}No tienes permisos para acceder a este recurso. Por ejemplo, intentas consultar un trabajo que no fue creado con tu API key.
{
"error": "unauthorized",
"message": "Solo puedes ver trabajos creados con tu API key"
}El recurso solicitado no existe o ha sido eliminado.
{
"error": "not_found",
"message": "Trabajo no encontrado"
}La solicitud está bien formada pero no se puede procesar. Por ejemplo, no se puede geocodificar una dirección.
{
"error": "geocoding_failed",
"message": "No se pudo geocodificar una o más direcciones",
"details": {
"pickup.address": "Dirección no encontrada o ambigua"
}
}Has excedido el límite de tasa. Por defecto, 100 solicitudes por minuto.
{
"error": "rate_limit_exceeded",
"message": "Has excedido el límite de solicitudes",
"retry_after_seconds": 60
}El campo retry_after_seconds indica cuántos segundos debes esperar antes de reintentar.
Error interno del servidor. Si este error persiste, contacta a soporte.
{
"error": "internal_server_error",
"message": "Ocurrió un error interno. Por favor, intenta de nuevo más tarde."
}El servicio está temporalmente no disponible por mantenimiento.
{
"error": "service_unavailable",
"message": "El servicio está en mantenimiento. Intenta de nuevo en unos minutos."
}Códigos de Error Específicos
validation_errorHTTP 400Uno o más campos de entrada son inválidos. Revisa el objeto details para ver qué campos tienen problemas.
unauthorizedHTTP 401 o 403API key inválida, faltante, revocada o intentando acceder a un recurso que no te pertenece.
not_foundHTTP 404El recurso solicitado no existe, ha sido eliminado o ha expirado (en el caso de trabajos borradores).
geocoding_failedHTTP 422No se pudo geocodificar una o más direcciones proporcionadas. Verifica que las direcciones sean válidas y completas.
photo_download_failedHTTP 422No se pudo descargar una o más fotos de las URLs proporcionadas. Verifica que las URLs sean accesibles públicamente.
rate_limit_exceededHTTP 429Has excedido el límite de solicitudes por minuto. Espera el tiempo indicado en retry_after_seconds antes de reintentar.
internal_server_errorHTTP 500Error interno del servidor. Si este error persiste, contacta a soporte en partners@recigo.es
service_unavailableHTTP 503El servicio está temporalmente no disponible por mantenimiento. Intenta de nuevo en unos minutos.
Mejores Prácticas para Manejo de Errores
1. Siempre verifica el código de estado HTTP
No asumas que todas las solicitudes son exitosas. Verifica el código de estado HTTP antes de procesar la respuesta.
2. Usa el campo "error" para lógica programática
El campo error es consistente y útil para manejo programático de errores (ej: switch/case statements).
3. Muestra el campo "message" al usuario
El campo message está diseñado para ser legible por humanos y puede mostrarse directamente al usuario.
4. Inspecciona "details" para errores de validación
Para errores de validación (400), el objeto details contiene información específica sobre qué campos son inválidos.
5. Implementa reintentos exponenciales para 429 y 5xx
Para errores de límite de tasa (429) o errores del servidor (5xx), implementa reintentos con backoff exponencial.
6. Registra errores para debugging
Registra todos los errores de la API con la respuesta completa para facilitar el debugging y análisis de problemas.
Ejemplo de Manejo de Errores
async function createJobWithErrorHandling() {
try {
const response = await fetch('https://api.recigo.es/v1/jobs', {
method: 'POST',
headers: {
'X-API-Key': process.env.RECIGO_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
// ... job data
}),
});
const data = await response.json();
// Verificar código de estado
if (!response.ok) {
// Manejo específico por código de error
switch (data.error) {
case 'validation_error':
console.error('Errores de validación:', data.details);
return { error: 'Por favor, verifica los datos ingresados' };
case 'unauthorized':
console.error('API key inválida');
return { error: 'Error de autenticación' };
case 'rate_limit_exceeded':
console.warn(`Límite excedido. Reintentar en ${data.retry_after_seconds}s`);
// Implementar reintento después de espera
await sleep(data.retry_after_seconds * 1000);
return createJobWithErrorHandling(); // Reintentar
case 'geocoding_failed':
console.error('Geocodificación falló:', data.details);
return { error: 'Una o más direcciones no son válidas' };
case 'internal_server_error':
console.error('Error del servidor:', data);
// Implementar reintento con backoff exponencial
return { error: 'Error del servidor. Intenta de nuevo más tarde' };
default:
console.error('Error desconocido:', data);
return { error: data.message || 'Ocurrió un error desconocido' };
}
}
// Éxito
return { success: true, job: data };
} catch (error) {
// Error de red u otro error no relacionado con la API
console.error('Error de red:', error);
return { error: 'Error de conexión. Verifica tu conexión a internet.' };
}
}
function sleep(ms: number) {
return new Promise(resolve => setTimeout(resolve, ms));
}Soporte
Si encuentras errores persistentes o necesitas ayuda:
- 📧 Email: partners@recigo.es
- 📚 Incluye el código de error completo y el contexto de la solicitud
- 🔍 Proporciona el job_id si el error está relacionado con un trabajo específico