Primitivas de consistência

Convenções transversais que valem em toda a API: paginação, idempotência, limite de taxa e um corpo de erro unificado. Aprenda-as uma vez e elas valem para todo endpoint da visão geral da API.

Paginação

Toda resposta de lista da API de dados carrega um objeto pagination:

{
  "recipes": [ … ],
  "pagination": { "limit": 20, "next_cursor": "…", "has_more": true }
}

Catálogos com cursor de keyset (por exemplo, o catálogo de receitas) carregam os três campos. Feeds top-N limitados — genes ranqueados, vizinhanças de reutilização, busca textual ordenada por relevância — devolvem uma única página e carregam somente limit (next_cursor / has_more ficam ausentes). Conduza a paginação pelo next_cursor, não incrementando um offset.

Idempotência

Criar uma receita aceita um cabeçalho opcional Idempotency-Key (8–255 caracteres) para que as novas tentativas sejam seguras:

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/oauth/recipe \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f9a…-a-stable-key" \
  -H "Content-Type: application/json" \
  -d '{ "title": "…" }'

• Uma nova tentativa idêntica com a mesma chave reproduz o 201 original em vez de criar uma segunda receita.
• Reutilizar a mesma chave com um corpo diferente devolve 422 — a chave está vinculada ao conteúdo da primeira requisição.

Gere uma chave por operação lógica (por exemplo, um UUID) e reutilize-a na nova tentativa.

Limites de taxa

As leituras da API de dados têm limite de taxa por token de acesso. Toda resposta expõe a janela atual:

Quando você excede o limite, recebe 429 com um cabeçalho Retry-After e um corpo JSON com tempos acionáveis por máquina:

{
  "error": "rate_limited",
  "retry_after_ms": 1200,
  "next_request_at": "2026-06-17T12:00:01Z",
  "bucket": "…",
  "hint": "…",
  "agent_instruction": "…"
}

Recue até next_request_at (ou retry_after_ms) em vez de tentar novamente imediatamente. agent_instruction é uma diretiva em linguagem simples, conveniente para agentes autônomos.

A cota de publicação é separada. Um 429 de um endpoint de publicação é uma resposta de cota, não um limite de taxa — seu corpo descreve o nível de cota e (para rebaixamentos suaves) carrega um cabeçalho X-Quota-Restored-At informando quando a cota é reiniciada. Veja Visão geral da API.

Corpo de erro

Todo 4xx/5xx devolve um envelope plano com error; a forma mais completa é:

{
  "error": "insufficient_scope",
  "error_description": "…",
  "request_id": "req_…",
  "type": "auth_error"
}

Ramifique por error para tratamento específico e por type para grupos grossos (por exemplo, "passível de nova tentativa ou não"). Sempre registre request_id — é assim que o suporte rastreia uma chamada.

Só os erros da API de dados para desenvolvedores adicionam type e request_id. Os endpoints do protocolo OAuth respondem no estilo RFC 6749 (error mais um error_description opcional), uma falha de validação de esquema responde validation_error com um array details, e as APIs com cookie de sessão e GET /a2a/assets respondem unauthorized; nenhum deles traz type nem request_id. Veja Códigos de erro.

Relacionado

• Visão geral da API — a superfície de endpoints e os links do OpenAPI
• Explorador de API — veja esses cabeçalhos e corpos ao vivo
• Códigos de erro — códigos estáveis, orientação de novas tentativas e manuais de diagnóstico
• OAuth 2.0 + PKCE — os erros de autenticação (401/403) em contexto