Errores y formato de respuesta

El sobre de respuesta estándar, el objeto de error y cómo resolver cada código que puede devolver el API.

Todas las respuestas del API comparten la misma estructura, sean de éxito o de error. Apréndela una vez y te sirve para todos los endpoints.

El sobre de respuesta

Las respuestas exitosas envuelven el resultado en data, con metadatos opcionales en meta:

{
  "success": true,
  "data": { "id": "clxq1w2e3r4t5y6u7i8o9p0a", "status": "DRAFT" },
  "meta": { "page": 1, "limit": 20, "total": 47, "totalPages": 3 }
}

Los errores llevan success: false y un objeto error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": {
        "contactName": ["contactName must be longer than or equal to 1 characters"],
        "postalCode": ["Postal code must be 4-6 digits"]
      }
    },
    "timestamp": "2026-07-17T12:00:00.000Z",
    "requestId": "req_abc123"
  }
}

Todos los códigos de error

Maneja errores por código, no por mensaje

const res = await fetch(url, options);
const body = await res.json();

if (!body.success) {
  switch (body.error.code) {
    case "RATES_EXPIRED":
      // refresca cotizaciones y reintenta
      break;
    case "INSUFFICIENT_BALANCE":
      // notifica al equipo de operaciones
      break;
    default:
      log.error(body.error.requestId, body.error.code);
  }
}

Revisa también details.code

Algunas validaciones devuelven 400 INVALID_INPUT con un código más específico anidado en error.details.code. Léelo cuando necesites distinguir el caso concreto: