Errors and conventions

RFC 7807, cursor pagination and idempotency — the three rules that hold across the whole API.

Errors: RFC 7807

Every error is application/problem+json with a stable code. The code is what your client maps; the detail is for a person and may change.

Situation	Status	`code`
No `Authorization`	401	`missing_bearer_credential`
Token that does not verify	401	`invalid_bearer_credential`
Missing permission	403	`insufficient_permission`
Nonexistent resource or another organization's	404	`not_found`
Unsupported method on an existing route	405	`method_not_allowed`
Write without `Idempotency-Key`	409	`missing_idempotency_key`
Key reused with a different body	409	`idempotency_conflict`
Body that violates the contract	422	`invalid_request_body`
Invalid cursor or `limit`	400	`invalid_cursor` / `invalid_limit`
AI rate limit	429	`rate_limited`

404 and not 403 for another organization is deliberate: a 403 would confirm the resource exists somewhere.

Pagination

json

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

The cursor is opaque. Use the nextCursor we returned; if you build it by hand, your client breaks the day pagination switches to 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

Idempotency

Every write requires an Idempotency-Key (16–128 characters).

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]

Returning the previous response for a different body would be answering a different question than the one you asked, so it is a 409 and not a silent replacement.

Mode

Every response carries x-ucotron-api-mode: sbox, x-ucotron-fixture-only: true and x-ucotron-no-external-provider-call: true. If any is missing, you are not talking to the sandbox.

Endpoints in this guide

The error conventions apply to the whole surface: see the full API reference.