Volver a Inicio

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"
  }
}
error

Código de error en formato snake_case. Útil para manejo programático.

message

Descripción legible del error en español. Puede mostrarse al usuario.

details

Objeto opcional con detalles adicionales sobre campos específicos que causaron el error.

Códigos de Estado HTTP

200OK

La solicitud fue exitosa. Se usa para consultas GET.

201Created

Un recurso fue creado exitosamente. Se usa para solicitudes POST que crean trabajos.

400Bad Request

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"
  }
}
401Unauthorized

API key inválida, faltante o revocada.

{
  "error": "unauthorized",
  "message": "API key inválida o faltante"
}
403Forbidden

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"
}
404Not Found

El recurso solicitado no existe o ha sido eliminado.

{
  "error": "not_found",
  "message": "Trabajo no encontrado"
}
422Unprocessable Entity

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"
  }
}
429Too Many Requests

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.

500Internal Server Error

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."
}
503Service Unavailable

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 400

Uno o más campos de entrada son inválidos. Revisa el objeto details para ver qué campos tienen problemas.

unauthorizedHTTP 401 o 403

API key inválida, faltante, revocada o intentando acceder a un recurso que no te pertenece.

not_foundHTTP 404

El recurso solicitado no existe, ha sido eliminado o ha expirado (en el caso de trabajos borradores).

geocoding_failedHTTP 422

No se pudo geocodificar una o más direcciones proporcionadas. Verifica que las direcciones sean válidas y completas.

photo_download_failedHTTP 422

No se pudo descargar una o más fotos de las URLs proporcionadas. Verifica que las URLs sean accesibles públicamente.

rate_limit_exceededHTTP 429

Has excedido el límite de solicitudes por minuto. Espera el tiempo indicado en retry_after_seconds antes de reintentar.

internal_server_errorHTTP 500

Error interno del servidor. Si este error persiste, contacta a soporte en partners@recigo.es

service_unavailableHTTP 503

El 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

error-handler.ts
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