/v1 es application/problem+json (RFC 9457) con un conjunto fijo de campos:
code para la lógica condicional, nunca detail: code es un contrato de máquina estable, mientras que detail está pensado para las personas y puede cambiar. param está presente cuando el error es atribuible a un parámetro concreto de la solicitud. Incluya request_id al ponerse en contacto con el soporte.
Códigos de error
El conjunto de códigos es cerrado: los códigos nuevos suponen un cambio en el contrato público y se anuncian a través del registro de cambios de la API. Una respuesta
retryable: true significa que la condición puede resolverse; no demuestra que una operación de escritura no haya surtido efecto. Reintente las lecturas con un número de intentos y un tiempo máximo finitos, retroceso exponencial y jitter. Respete Retry-After cuando esté presente, incluso en una respuesta 409 o 429 reintentable.
En las mutaciones, siga el contrato de idempotencia y recuperación documentado de la operación. Conserve la clave y la solicitud originales cuando la operación lo admita. No genere una clave nueva tras un tiempo de espera agotado o un 5xx: podría repetir una escritura que se realizó correctamente. Un encabezado Idempotency-Key no ofrece ninguna protección en una operación que no lo admite.