Regras da API

Estas regras valem em todas as operações da API. Nesta página:

• Erros: O formato dos erros, a lista de códigos e o que fazer em cada caso.
• Limites: Quantos pedidos pode fazer, como saber quantos restam e o que fazer quando passa o limite.
• Paginação: Como as operações de lista dividem os resultados em páginas.
• Repetições (Idempotency-Key): Como repetir um pedido com segurança, sem fazer a mesma coisa duas vezes.
• Sandbox e Produção: Os dois modos da API: o que as chaves sandbox_ e prod_ fazem, e como confirmar o modo em cada pedido.

Erros

Formato

Todos os erros têm a mesma forma:

{
  "error": {
    "code": "rate_limited",
    "message": "Demasiados pedidos. Tente de novo daqui a pouco.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "retry_after": 42
    }
  }
}

Códigos

Repetir ou não repetir

• Vale a pena repetir, com espera: 429, 500, 502 e 503.
• Não vale a pena repetir sem mudar nada: todos os outros.

Num pedido POST, envie sempre Idempotency-Key logo na primeira tentativa e repita com o mesmo valor.

Comunicar um problema

Indique ao suporte o correlation_id, a hora do pedido e a operação. Nunca envie a chave: o suporte não precisa dela.

Limites

Limites de pedidos

Estes são os valores actuais e podem mudar. Nos seus programas, leia os cabeçalhos em vez de fixar os números. GET /v1/ping e GET /v1/openapi.json contam sempre por IP, mesmo com chave.

Cabeçalhos

As respostas trazem:

A operação GET /v1/limits mostra os mesmos valores, mais o limite de gastos da chave.

Quando passa o limite

A API responde 429 com o código rate_limited e o cabeçalho Retry-After, que indica quantos segundos deve esperar.

• Espere pelo menos esse tempo antes de repetir.
• Se o 429 se repetir, aumente a espera a cada tentativa.
• Evite ciclos de consulta muito rápidos.

Tamanho do pedido

O corpo de um pedido pode ter até 1048576 bytes (1 MB).

Paginação

Parâmetros

Exemplo do que se junta ao endereço:

?page=2&per_page=50

Resposta

Os resultados vêm em data, e meta indica a página e o total:

{
  "data": [],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 120,
    "total_pages": 3
  }
}

Ler todas as páginas

Comece em page=1 e continue enquanto page for menor do que total_pages. Cada página conta como um pedido para os limites.

Repetições (Idempotency-Key)

Para que serve

Se a ligação falhar a meio de um pedido, não sabe se ele chegou a ser feito. Com o cabeçalho Idempotency-Key, pode repetir o pedido sem risco de registar ou cobrar duas vezes.

Como usar

Gere um valor único para cada operação e envie-o num pedido POST:

Idempotency-Key: 0f8fad5b-d9cb-469f-a165-70867728950e

O valor pode ter até 255 caracteres visíveis. Um UUID serve bem. Repita o mesmo valor só quando repetir a mesma operação.

O que acontece

O valor fica reservado para cada chave durante 24 horas.

Depois de uma falha

• Se não recebeu resposta: repita o pedido com o mesmo valor.
• Se recebeu 409 porque o primeiro ainda está em curso: espere um pouco e repita.
• Se recebeu 409 porque o corpo é outro: use um valor novo, se for mesmo uma operação diferente.

Sandbox e Produção

Dois modos

O endereço é o mesmo nos dois modos: é a chave que decide.

O que a resposta diz

• Todas as respostas com chave trazem o cabeçalho X-API-Mode, com sandbox ou production.
• As escritas simuladas trazem também X-API-Simulated: true.
• Enquanto a API está em preparação, nem as chaves prod_ alteram a conta nem cobram: as escritas são simuladas e o campo writes_simulated de GET /v1/token vem a true.
• As chaves criadas durante a preparação, de qualquer modo, são revogadas quando a API abrir, e o dono da conta recebe um aviso por e-mail. Depois disso, crie chaves novas.

Saber o modo da chave

O campo mode da operação GET /v1/token diz sandbox ou production.

Para garantir que um programa nunca corre com a chave errada, envie o cabeçalho X-API-Mode no pedido. Se não coincidir com o modo da chave, a API recusa com invalid_request e a razão mode_mismatch.

Playground

Cada operação, na página da sua área, tem o botão Playground, para fazer pedidos a partir do navegador, sem sair da página.

• A chave que escrever fica só na memória dessa página: não é guardada nem vai no endereço.
• Use uma chave sandbox_. As chaves prod_ agem na sua conta.

Passar para Produção

Quando o programa estiver pronto, crie uma chave prod_ com as permissões mínimas, na página API. O prefixo é a única diferença no pedido.