API del Portal
Errores
Formato RFC 7807 y tabla completa de códigos de error de la Tikra Portal API.
La API devuelve errores en formato RFC 7807 (application/problem+json).
Ejemplo
{
"type": "https://api.tikra.com/errors/auth/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "Esta API key no tiene el scope requerido: write:orders.",
"instance": "/api/v1/portal/orders",
"request_id": "req_01HX..."
}El header X-Request-Id viene en TODAS las responses (success y error). Guardalo si necesitás soporte.
Tipos de error
auth/* (401–403)
type | HTTP | Significado | Cómo arreglar |
|---|---|---|---|
auth/missing-key | 401 | Falta Authorization: Bearer ... | Mandá el header |
auth/invalid-key | 401 | Key no existe o fue revocada | Creá una nueva |
auth/expired-key | 401 | Key pasó su expires_at | Creá una nueva |
auth/insufficient-scope | 403 | Falta el scope para este endpoint | Creá key con el scope correcto |
auth/ip-not-allowed | 403 | IP origen no está en allowlist | Remové el allowlist o agregá la IP |
validation/* (400)
type | HTTP | Significado |
|---|---|---|
validation/invalid-body | 400 | Body con campos inválidos |
validation/missing-field | 400 | Falta un campo requerido |
validation/invalid-cursor | 400 | El cursor de paginación está corrupto |
rate-limit/exceeded (429)
Header Retry-After indica los segundos a esperar. Implementá backoff exponencial.
idempotency/* (409)
type | HTTP | Significado |
|---|---|---|
idempotency/key-reused-with-different-body | 409 | El mismo Idempotency-Key se reusó con un body distinto. Generá un key nuevo. |
idempotency/in-progress | 409 | Un request con el mismo Idempotency-Key está siendo procesado en paralelo. Esperá unos segundos y reintentá. |
not-found/* (404)
not-found/resource— el recurso no existe o no pertenece a tu cliente.not-found/endpoint— la ruta no existe en esta versión.
conflict/* (409)
conflict/resource-state— el recurso está en un estado incompatible (ej. cancelar un pedido ya entregado).
server/* (5xx)
server/internal-error— bug del lado de Tikra. Reintentá con backoff.server/upstream-error— falla de un servicio dependiente (Storage, AFIP, etc.).
Recomendaciones de retry
| Status | ¿Reintentar? | Cómo |
|---|---|---|
| 4xx (excepto 429) | No | Es bug del cliente |
| 429 | Sí | Esperar Retry-After segundos |
| 5xx | Sí | Backoff exponencial: 1s → 2s → 4s → 8s, max 5 intentos |