Guia

Erros

Todo erro das duas superfícies responde no mesmo formato, com um code estável para o seu código tratar e uma mensagem em português para você ler.

O formato

JSON

{
  "error": "campo não filtrável: notes",
  "code": "FilterFieldNotAllowed",
  "requestId": "req-8f3c1a2e"
}

Campo	É
`code`	O identificador estável do erro. Trate por ele, nunca pelo texto da mensagem
`error`	A mensagem legível. Nos erros 4xx ela é a instrução de como corrigir
`requestId`	Identifica esta requisição no nosso log. Guarde ao relatar

Trate pelo código, não pela mensagem

O code faz parte do contrato e não muda dentro da v1 — veja Versionamento. Já o texto de error pode ser reescrito a qualquer momento para ficar mais claro. Código que compara a mensagem quebra numa melhoria de redação.

Acesso

Código	HTTP	O que houve e o que fazer
`Unauthorized`	401	Token ausente, inválido, revogado ou expirado. Confira o cabeçalho `Authorization: Bearer oag_…`; se estiver certo, o token não vale mais — crie outro em Integrações
`IpNotAllowed`	403	O token tem lista de IPs e a chamada veio de fora dela. Ajuste a lista ou use um token sem restrição de origem
`ScopeMissing`	403	O token não carrega o escopo daquela coleção. Escopo não se acrescenta depois: crie um token novo com os escopos certos
`OpenAGROsNotLicensed`	403	A organização não tem o OpenAGROs no contrato. Nenhum token vai funcionar até isso mudar
`RateLimited`	429	Passou do limite por minuto do token. Espere a virada do minuto e repita — veja Limite de requisições

Consulta

São erros de como a consulta foi escrita. Todos trazem, na mensagem, o campo ou o trecho que causou o problema.

Código	HTTP	O que houve e o que fazer
`FilterRequired`	400	A coleção exige uma janela de datas e a consulta não trouxe nenhuma. No REST não há como declará-la: use a versão OData
`FilterFieldNotAllowed`	400	O campo existe, mas não é filtrável. Os filtráveis estão marcados na página da coleção
`FilterInvalid`	400	O `$filter` não é uma expressão OData válida. Aspas simples em texto, datas em `AAAA-MM-DD`
`OrderByFieldNotAllowed`	400	O campo existe, mas não é ordenável
`OrderByInvalid`	400	Direção inválida no `$orderby`: só `asc` e `desc`
`SelectFieldUnknown`	400	O `$select` pediu um campo que a coleção não tem. Confira a grafia — os nomes são em inglês e diferenciam maiúsculas
`UnsupportedPaging`	400	Combinação de paginação que a coleção não aceita. Veja os limites de `pageSize` em REST
`validation_error`	400	Um parâmetro está fora do formato esperado. A mensagem nomeia o campo
`NotFound`	404	Coleção ou registro inexistente para este token

Capacidade não suportada

O 501 é diferente do 400: a consulta está correta, e é a coleção que não sabe aplicar aquela operação no servidor.

Código	HTTP	O que houve e o que fazer
`FilterUnsupported`	501	A coleção não filtra no servidor
`OrderByUnsupported`	501	A coleção não ordena no servidor

Por que 501 e não uma resposta filtrada

Filtrar depois de paginar filtraria só a página, e a API devolveria um pedaço da coleção com cara de resultado completo — o erro só apareceria no total do seu relatório, semanas depois. Preferimos recusar: o Power BI entende o 501 e passa a filtrar do lado dele.

Erros nossos

Qualquer 5xx é problema do nosso lado. A mensagem é deliberadamente genérica e vem com uma referência:

JSON

{
  "error": "Erro ao consultar a origem dos dados. Informe a referência 3f2c1c20-d4ad-4386-bc44-097bf481792a.",
  "code": "ErpQueryError",
  "requestId": "req-11b0d7c4"
}

O detalhe técnico fica no nosso log, não na resposta — mensagem de erro de banco carrega nome de tabela, de coluna e endereço de servidor, e isso não pode viajar numa API aberta. Guarde a referência: é ela que localiza a ocorrência exata quando você nos procurar.

Limite de requisições

O limite é por token, por minuto, no valor escolhido na criação, até o teto de 60 da superfície aberta. A janela é fixa: ao receber 429, espere a virada do minuto e repita.

Se você importa muito volume, o caminho não é subir o limite — é pedir menos vezes. No OData, $filter e $select reduzem o que trafega por requisição; no REST, pageSize=200 é o maior salto por página.