Referência

As regras que valem para todos os endpoints: envelopes, status, paginação, filtros, limites e erros.

O comportamento comum a toda a API. Vale para os dez recursos, sem exceção: o que vem no corpo, como paginar e filtrar, quanto se pode chamar por minuto e como interpretar cada código de erro.

Resumo rápido

Assunto	Regra	Detalhes
Envelope de sucesso	{ "data": ... }, com meta nas listagens	Convenções
Envelope de erro	{ "errors": [{ "field", "detail" }] }	Erros
Escrita	PUT é parcial; null limpa o campo	Convenções
Paginação	?page=1&per_page=30, máximo 100	Paginação, ordenação e filtros
Ordenação	?sort=campo e ?sort=-campo	Paginação, ordenação e filtros
Filtros	sufixos __contains, __gte, __lte, __gt, __lt	Paginação, ordenação e filtros
Limites	120 req/min por chave, 300 req/min por IP	Limites de requisição

Códigos de status em uma linha

Código	Leitura prática
200 / 201 / 204	deu certo (leitura ou atualização / criação / exclusão)
400	o problema está na URL ou no formato do corpo
401	o problema está na chave
403	a chave é válida, falta o escopo
404	o id não existe ou não é desta conta
422	o corpo chegou, mas foi reprovado na validação
429	reduza o ritmo e tente de novo após RateLimit-Reset
500	erro do servidor, acione o suporte com horário e rota

Erros de validação e de query trazem todos os problemas de uma vez no array errors. Percorra o array inteiro antes de decidir o que corrigir.

Nesta seção