Errores y convenciones

RFC 7807, paginación por cursor e idempotencia — las tres reglas que valen para toda la API.

Errores: RFC 7807

Todo error es application/problem+json con un code estable. El code es lo que tu cliente mapea; el detail es para una persona y puede cambiar.

Situación	Status	`code`
Sin `Authorization`	401	`missing_bearer_credential`
Token que no verifica	401	`invalid_bearer_credential`
Falta el permiso	403	`insufficient_permission`
Recurso inexistente o de otra organización	404	`not_found`
Método no soportado en una ruta que existe	405	`method_not_allowed`
Sin `Idempotency-Key` en una escritura	409	`missing_idempotency_key`
Clave reusada con otro cuerpo	409	`idempotency_conflict`
Cuerpo que no cumple el contrato	422	`invalid_request_body`
Cursor o `limit` inválidos	400	`invalid_cursor` / `invalid_limit`
Rate limit de AI	429	`rate_limited`

404 y no 403 para otra organización es deliberado: un 403 confirmaría que el recurso existe en algún lado.

Paginación

json

{ "data": [ … ], "page": { "nextCursor": "eyJvIjoyNX0", "previousCursor": null, "limit": 25, "hasMore": true } }

El cursor es opaco. Usá el nextCursor que te devolvimos; si lo construís a mano, tu cliente se rompe el día que la paginación pase a ser por keyset.

bash

curl -sS "$SBOX/v1/aois?limit=1" -H "authorization: Bearer $TOKEN"
curl -sS "$SBOX/v1/aois?limit=1&cursor=<nextCursor>" -H "authorization: Bearer $TOKEN"
curl -sS "$SBOX/v1/aois?cursor=no-soy-un-cursor" -H "authorization: Bearer $TOKEN"  # 400

Idempotencia

Toda escritura pide Idempotency-Key (16–128 caracteres).

Fuente del diagrama (mermaid)

flowchart TD
    A[POST con Idempotency-Key] --> B{¿Clave vista antes?}
    B -- no --> C[Se crea · 201]
    B -- sí, mismo cuerpo --> D[Se devuelve la respuesta anterior · 201]
    B -- sí, otro cuerpo --> E[409 idempotency_conflict]

Devolverte la respuesta anterior ante otro cuerpo sería contestarte una pregunta distinta de la que hiciste, así que es un 409 y no un reemplazo silencioso.

Modo

Cada respuesta trae x-ucotron-api-mode: sbox, x-ucotron-fixture-only: true y x-ucotron-no-external-provider-call: true. Si alguno falta, no estás hablando con el sandbox.

Endpoints de esta guía

Las convenciones de error aplican a toda la superficie: ver la referencia de API completa.