Diagnóstico y go-live

1. Identificá dónde falló

Antes de reintentar, determiná si el problema está en autenticación, customer search/create, purchase, lectura de state o en una superficie POS/operator separada.

2. Revisá auth, scope y tenant

• missing_api_key / invalid_api_key → corregí la credencial server-side.
• insufficient_scope → verificá el scope exacto de la operación.
• tenant_mismatch, invalid_tenant_hint, ambiguous_tenant_hint → corregí el contexto; el tenant de la credencial es autoritativo.
• rate_limited → seguí los headers que la respuesta incluya.

3. Customer search y create

• customer: null en search es un miss esperado, no un error de transporte.
• customer_email_conflict se recupera buscando nuevamente la identidad.
• Ante un create ambiguo, buscá antes de volver a crear.

4. Purchase

• idempotency_conflict → no repitas el request sin corregir el uso de la key.
• idempotency_in_progress → repetí únicamente la misma operación con la misma key y payload.
• purchase_reconciliation_required → preservá el contexto y verificá state antes de una nueva acción.

5. Guardá un paquete de diagnóstico

• x-request-id.
• Método y path de la operación pública.
• Timestamp con timezone.
• Tenant, program y customer IDs necesarios para reproducir el contexto.
• HTTP status, error.code y mensaje público.
• Idempotency-Key y transactionId cuando correspondan.
• Request redactado, sin API keys, tokens, cookies ni secretos.

6. Si el resultado sigue siendo ambiguo

Pausá nuevas escrituras que puedan duplicar efectos, preservá el request original y reconciliá el estado observable antes de reanudar el flujo.