Conceptos

Errores

Todas las respuestas tienen la misma forma; los errores traen un código estable y qué hacer.

Cada respuesta es un objeto con version: 1, ok, progreso y requiereRevision. Si ok es true trae datos; si es false trae error. Decidí siempre por error.codigo y error.recuperacion, nunca por el texto de mensaje (que está pensado para mostrarle a la clienta y puede cambiar).

{
  "version": 1,
  "ok": false,
  "progreso": {
    "principal": "NO_GUARDADO"
  },
  "requiereRevision": false,
  "error": {
    "dominio": "compras",
    "codigo": "HORARIO_NO_DISPONIBLE",
    "mensaje": "Ese horario ya no está disponible.",
    "categoria": "ESTADO",
    "reintentable": false,
    "recuperacion": "RELEER_Y_CONFIRMAR"
  }
}

Campos del error

Campo	Qué es
`dominio`	`api` (la puerta: clave, origen, límites, formato) o `compras` (el motor de reservas).
`codigo`	Código estable. Es el que tenés que usar en tu código.
`mensaje`	Texto en español para mostrar.
`categoria`	`ENTRADA`, `ACCESO`, `ESTADO`, `IDENTIDAD`, `PROVEEDOR` o `TECNICO`.
`reintentable`	`true` solo si repetir el mismo pedido, con la misma `Idempotency-Key`, puede andar.
`recuperacion`	Qué hacer: ver la tabla de abajo.
`campos`	Con `ENTRADA_INVALIDA`: la lista de campos con problema (`campo`, `codigo`, `mensaje`).
`referenciaDiagnostico`	Con errores técnicos: un identificador para pedir soporte. No trae detalles internos.

Qué hacer según la recuperación

Recuperación	Qué hacer
`CORREGIR_ENTRADA`	Corregí los datos (mirá `campos`) y mandá un pedido nuevo.
`RELEER_Y_CONFIRMAR`	El estado cambió (por ejemplo, alguien tomó el horario). Volvé a consultar la disponibilidad y pedile a la clienta que elija otra vez.
`REINTENTAR_MISMA_INTENCION`	Reintentá el mismo pedido con la misma `Idempotency-Key`, respetando `Retry-After` si viene.
`CONSULTAR_ESTADO`	No se sabe si se guardó. Reintentá con la misma clave de idempotencia o consultá la reserva.
`REVISION_HUMANA`	Necesita que alguien del negocio lo mire. No reintentes en bucle.
`NO_REINTENTAR`	Repetir da lo mismo.

Progreso

progreso.principal dice qué se sabe de la operación: CONSULTADO (lecturas), NO_GUARDADO, GUARDADO (la reserva existe pero falta algo, por ejemplo el pago), CONFIRMADO o DESCONOCIDO. En reservas puede venir progreso.pago: PENDIENTE, CONFIRMADO, EN_REVISION o INCIERTO. Un error nunca se presenta como algo mayor a lo que el servidor confirmó.

Códigos de la API (dominio api)

HTTP	Código	Reintentable	Mensaje
404	`API_NO_HABILITADA`	No	La API externa no está habilitada.
403	`PLAN_SIN_API`	No	La API está incluida en el plan Enterprise. El negocio puede cambiar de plan desde su panel.
401	`CREDENCIAL_FALTANTE`	No	Mandá la clave en Authorization: Bearer <clave>.
401	`CREDENCIAL_INVALIDA`	No	La clave no es válida.
401	`CREDENCIAL_REVOCADA`	No	La clave fue revocada por el negocio.
403	`CLAVE_SECRETA_EN_NAVEGADOR`	No	La clave secreta es solo para servidores: desde el navegador usá la clave pública.
403	`ORIGEN_NO_PERMITIDO`	No	Este sitio no está autorizado para usar la clave.
403	`SCOPE_FALTANTE`	No	La clave no tiene permiso para esta operación.
429	`LIMITE_USO`	Sí	Demasiados pedidos. Esperá unos segundos y reintentá con los mismos datos.
400	`IDEMPOTENCY_KEY_FALTANTE`	No	Mandá la cabecera Idempotency-Key: una clave estable por operación.
400	`IDEMPOTENCY_KEY_INVALIDA`	No	Idempotency-Key: entre 8 y 100 caracteres A-Z, a-z, 0-9, punto, guion, guion bajo o dos puntos.
400	`ENTRADA_INVALIDA`	No	Revisá los datos enviados.
404	`NO_ENCONTRADO`	No	No existe o no pertenece a este negocio.
409	`SERVICIO_DERIVADO_WHATSAPP`	No	Este servicio se agenda por WhatsApp con la profesional, no por la API.
500	`ERROR_TECNICO`	Sí	No pudimos completar el pedido. Reintentá con los mismos datos.
400 o 404	`CONSULTA_RECHAZADA`	No	Lecturas: el catálogo o la disponibilidad rechazaron el pedido (por ejemplo, un servicio que no existe). El mensaje explica por qué.

Códigos de la reserva (dominio compras)

HTTP	Código	Recuperación	Reintentable
400	`ENTRADA_INVALIDA`	`CORREGIR_ENTRADA`	No
400	`SOLICITUD_NO_PERMITIDA`	`CORREGIR_ENTRADA`	No
404 o 400	`CATALOGO_NO_DISPONIBLE`	`CORREGIR_ENTRADA`	No
400	`DESCUENTO_NO_APLICABLE`	`CORREGIR_ENTRADA`	No
409	`HORARIO_NO_DISPONIBLE`	`RELEER_Y_CONFIRMAR`	No
409	`ESTADO_CAMBIO`	`RELEER_Y_CONFIRMAR`	No
409	`IMPORTE_NO_CORRESPONDE`	`RELEER_Y_CONFIRMAR`	No
409	`OPERACION_NO_PERMITIDA`	`NO_REINTENTAR`	No
400 o 409	`CONFIGURACION_INCOMPLETA`	`REVISION_HUMANA`	No
409	`DATOS_INCONSISTENTES`	`REVISION_HUMANA`	No
409	`COMPRA_GUARDADA_REVISAR`	`CONSULTAR_ESTADO`	No
409	`AGENDA_OCUPADA`	`REINTENTAR_MISMA_INTENCION`	Sí
409	`CONFLICTO_INTENCION`	`REVISION_HUMANA`	No
409	`PAGO_NO_VERIFICADO`	`REVISION_HUMANA`	No
404	`NO_ENCONTRADO`	`NO_REINTENTAR`	No
403	`SIN_ACCESO`	`NO_REINTENTAR`	No