Códigos de error

Todo error usa un envoltorio con code estable. Ramifique por error.code, no solo por message mutable o el estado HTTP.

{
  "error": {
    "code": "validation_failed",
    "message": "La validación de la solicitud ha fallado.",
    "request_id": "req_01HQ...",
    "details": [
      {
        "field": "territories",
        "issue": "zod_invalid_format",
        "message": "El valor tiene un formato no válido."
      }
    ]
  }
}

request_id refleja su X-NU-Request-Id o un valor del servidor. Inclúyalo al pedir soporte. details aparece en errores de validación.

Referencia de códigos

Código	HTTP	Significado	Acción habitual
`invalid_api_key`	401	Clave ausente, mal formada, desconocida o caducada	Envíe una clave Authorization: Bearer válida del entorno correcto
`api_key_revoked`	401	Clave revocada	Sustitúyala por una activa (04)
`invalid_approval_token`	401	Token de aprobación no válido, caducado o ya usado	Solicite otro token y úselo una vez (04)
`invalid_application_token`	401	Referencia o token de estado incorrecto o caducado	Use las credenciales mostradas en la respuesta inicial
`missing_scope`	403	Falta el ámbito necesario	Conceda el ámbito; consulte la tabla (03)
`production_key_required`	403	Clave Sandbox usada en endpoint de Production	Repita con una clave nsp_live_
`organization_not_approved`	403	Organización aún no aprobada	Espere aprobación o complete el alta (02)
`resource_not_found`	404	Recurso inexistente o no visible	Compruebe el ID y acceso de la organización
`validation_failed`	422	Falló la validación del cuerpo o parámetro	Corrija los campos de details
`rate_limit_exceeded`	429	Límite por clave alcanzado	Aplique backoff con Retry-After (12)
`license_not_active`	403	No hay acuerdo ACTIVE que autorice	Active el acuerdo o su API de Production (06)
`territory_not_allowed`	403	Falta country o acuerdo/clave no permite country, origin o IP	Envíe country permitido; incluya origin admitido y revise allowed_ips
`episode_not_licensed`	403	Episodio no listo, sin activo listo o fuera de licencia	Licencie el activo listo o use un episodio elegible
`duplicate_event_id`	409	event_id ya aceptado; sin efecto idempotente	Trátelo como éxito; no reintente con otro ID
`invalid_playback_session`	400	Sesión desconocida o no válida	Use playback_session_id devuelto por la API
`playback_concurrency_limit`	429	Demasiadas sesiones activas para espectador y acuerdo o título	Revoque una sesión o espere a que termine o caduque
`settlement_not_disputable`	409	Liquidación no impugnable	Impugne solo cuando el estado lo permita (09)
`conflict`	409	Recurso existente o solicitud concurrente en curso	Reintente la operación idempotente o concilie el recurso
`service_unavailable`	503	El servicio requerido no está disponible temporalmente.	Reintente llamadas idempotentes con backoff exponencial.
`internal_error`	500	Error inesperado del servidor	Reintente con backoff; si persiste, contacte con request_id

Pautas de tratamiento

401 — Corrija la autenticación; no reintente a ciegas.
403 — Problema de autorización, organización o derechos. Reintentar no sirve hasta cambiar el permiso.
404 — Compruebe el ID y visibilidad de la organización.
422 — Revise details[] y corrija la solicitud.
409 — Depende del código: duplicate_event_id ya fue aceptado y cuenta como éxito; settlement_not_disputable no permite la acción; conflict indica recurso existente o solicitud en curso. Reintente o concilie según proceda.
429 — Respete Retry-After; consulte Límites de velocidad.
5xx — Reintente llamadas idempotentes con backoff exponencial.

Mapeo de restricciones de base de datos

Errores conocidos se mapean a 4xx en vez de 500, incluidas carreras read-then-write con filas eliminadas:

Condición de base de datos	HTTP	error.code
Fila no encontrada al escribir (P2025)	404	`resource_not_found`
Violación de unicidad (P2002)	409	`conflict`
Violación de clave externa (P2003)	422	`validation_failed`