API: errores, límites y versiones

​

Cómo se ve un error

{
  "error": {
    "code": "quote_expired",
    "message": "La cotización de envío no existe o venció. Pedí una nueva.",
    "details": {}
  }
}

• code es estable: decidí por code y por el status HTTP.
• message es un texto en castellano para una persona. Puede cambiar sin aviso: no lo uses en tu lógica.
• details es siempre un objeto, vacío ({}) si no hay nada que agregar. Su forma depende de code: ver Qué trae details. La especificación la publica código por código, en los esquemas Error_<código>.

​

Respuestas que no son de la API

​

Tabla de errores

​

Qué trae details

​

validation_error

• Las rutas son las del cuerpo o de la query, con punto y el índice de la lista: shipping_address.number, items.0.quantity.
• Un error que no es de un campo en particular va bajo la clave _.

{
  "error": {
    "code": "validation_error",
    "message": "(texto para una persona)",
    "details": {
      "fields": {
        "shipping_address.number": "Campo obligatorio.",
        "items.0.quantity": "quantity va de 1 a 20."
      }
    }
  }
}

​

province_required

{
  "error": {
    "code": "province_required",
    "message": "(texto para una persona)",
    "details": {
      "fields": {
        "province": "El código postal no está en nuestra tabla: mandá también la provincia."
      }
    }
  }
}

​

out_of_stock

{
  "error": {
    "code": "out_of_stock",
    "message": "(texto para una persona)",
    "details": {
      "items": [{ "index": 0, "product_id": 812, "variant_id": 4410 }]
    }
  }
}

​

variant_not_orderable

{
  "error": {
    "code": "variant_not_orderable",
    "message": "(texto para una persona)",
    "details": {
      "items": [{ "index": 1, "product_id": 812, "variant_id": 4411 }]
    }
  }
}

​

billing_data_required

{
  "error": {
    "code": "billing_data_required",
    "message": "(texto para una persona)",
    "details": { "missing_fields": ["cuit", "phone"] }
  }
}

​

product_archived

{
  "error": {
    "code": "product_archived",
    "message": "(texto para una persona)",
    "details": { "product_ids": [812] }
  }
}

​

external_id_conflict

{
  "error": {
    "code": "external_id_conflict",
    "message": "(texto para una persona)",
    "details": { "order_id": 1043 }
  }
}

​

order_in_progress

{
  "error": {
    "code": "order_in_progress",
    "message": "(texto para una persona)",
    "details": { "order_id": 1043 }
  }
}

​

rate_limited

{
  "error": {
    "code": "rate_limited",
    "message": "(texto para una persona)",
    "details": { "retry_after_seconds": 42 }
  }
}

​

too_many_unpaid_orders

{
  "error": {
    "code": "too_many_unpaid_orders",
    "message": "(texto para una persona)",
    "details": { "max_unpaid_orders": 20 }
  }
}

​

payload_too_large

{
  "error": {
    "code": "payload_too_large",
    "message": "(texto para una persona)",
    "details": { "limit_bytes": 65536 }
  }
}

​

invalid_transition

{
  "error": {
    "code": "invalid_transition",
    "message": "(texto para una persona)",
    "details": { "status": "pending_payment", "event": "ship" }
  }
}

​

Reintentos

• Adentro de un checkout (hay un comprador esperando): esperá dentro del pedido sin pasar de 30 segundos por espera. Si Retry-After pide más de 30 segundos, no esperes: guardá el pedido como pendiente y seguí con la receta de abajo, en segundo plano.
• En segundo plano (sincronizar el catálogo, la receta de pendientes, ponerte al día): esperá lo que pida Retry-After, sea lo que sea, antes del próximo intento. Un 429 de un límite por minuto pide como mucho 60 segundos; uno del límite diario puede pedir horas: reprogramá el trabajo para ese momento en vez de dejar un proceso esperando.
• Al crear un pedido, reintentá siempre con el mismo external_id y el mismo cuerpo. Es lo único que garantiza que no se duplique. Si el timeout se cumple antes de la respuesta, no sabés si el pedido se creó: reintentá igual.

​

Receta cuando te quedaste sin intentos

1. Guardá el pedido en tu sistema como pendiente, con el cuerpo exacto que mandaste.
2. Antes de reintentar, consultá GET /orders?external_id=<tu id>.
3. Si data trae un pedido, ya está creado: usá ése.
4. Si data viene vacío, mandá de nuevo el mismo cuerpo con el mismo external_id.

​

Límites

• Los límites son por cuenta (todas tus claves suman juntas) y por ventana fija: un minuto, o un día para el tope diario de altas.
• Cuenta toda solicitud con una clave válida, también las que terminan en error (400, 404, 409) y los reintentos que devuelven 200. Un bucle que reintenta un 409 de negocio se come el cupo.
• Al pasarte recibís 429 rate_limited con la cabecera Retry-After (segundos) y el mismo número en details.retry_after_seconds. No reintentes antes de eso (ver Reintentos).
• Las respuestas no traen cabeceras de cupo restante (RateLimit-*): medí tu ritmo con esta tabla.
• Bajar las imágenes de los productos no cuenta para estos límites.

​

Versiones

• La URL base (/api/v1) es parte del contrato y no cambia.
• Dentro de v1 sólo hay cambios que suman: campos nuevos en las respuestas, códigos de error nuevos, eventos nuevos, valores nuevos de cualquier campo de lista cerrada (status, hold_reason, cancel_reason, product_type, payment.status, tracking.carrier, el type de un aviso).
• Tu código tiene que ignorar los campos que no conoce y no romperse ante un valor nuevo. Tratá un status desconocido como “en curso”, un cancel_reason desconocido como null, y respondé 2xx a un evento desconocido.
• Los enum de la especificación son los valores de hoy. Si validás respuestas contra la especificación, que un valor nuevo no te haga descartar la respuesta: tratalo como dice cada página (“en curso” para un estado, 2xx y descartar para un aviso). El type de un aviso ya figura abierto en la especificación (texto, con los de hoy en examples).
• Un cambio que rompe (sacar o renombrar un campo, cambiar un tipo o un significado) sale como v2, con 90 días de aviso. Durante ese plazo v1 sigue funcionando.
• La especificación vigente, en formato OpenAPI, la sirve la propia API en GET /api/v1/openapi.json, sin clave. La guía canónica en texto plano, en GET /api/v1/llms.txt, también sin clave. Ver cuál vale si difieren.

​

Checklist antes de pasar a producción

1. La clave de pruebas (gk_stg_) está en GUDINK_API_KEY en tu servidor y GUDINK_API_BASE apunta al entorno de pruebas. Tu cliente HTTP manda un User-Agent propio. GET /me responde y billing_complete es true.
2. El catálogo se sincroniza paginando hasta next_cursor: null. Guardás cada variante por el par (product_id, variant_id), con su precio, y el updated_at del producto. Las imágenes están alojadas en tu sitio.
3. El checkout valida los formatos de Qué va en cada campo antes de cobrar.
4. El checkout cotiza el envío con el carrito real y muestra las opciones con su price. Si responde province_required, pide la provincia. Si ofrecés retiro en sucursal, tu comprador elige una sucursal de pickup_points antes de pagar.
5. El pedido se crea con un external_id único (prefijo de tu instalación más tu número de pedido) y con la province de la cotización. Ante un error de red o un 5xx se reintenta con el mismo external_id y el mismo cuerpo, según Reintentos. Después de cada 200 o 201 tu sistema mira status: si es cancelled, ese pedido no va.
6. Tu sistema maneja out_of_stock después de haber cobrado, sin reintentar en bucle.
7. Hay alguien, o algo, que paga los pedidos en tu panel antes de expires_at (72 horas), con una alarma propia antes del vencimiento (ver Pagar es una tarea de todos los días). En pruebas, con la simulación. Un order.cancelled con cancel_reason: "unpaid_expired" quiere decir que se te pasó.
8. El destino de avisos está dado de alta, verifica la firma y deduplica por webhook-id. “Mandar prueba” llega bien.
9. Con order.shipped u order.tracking_updated tu comprador recibe el seguimiento. Gudink no le escribe.
10. Todo lo anterior funciona en el entorno de pruebas, con el recorrido de punta a punta. Recién ahí, clave de producción (gk_live_) y GUDINK_API_BASE="https://app.gudink.com/api/v1".