Skip to main content
Toda resposta de erro da API /v1 segue o RFC 7807 e é retornada com Content-Type: application/problem+json. Isso vale para os dois motores — Motor de CPF/CNPJ (POST /analyses, GET /analyses/{id}) e Motor de Borderô (POST /operations, GET /operations/{id}, GET /operations/{id}/result): mesmo formato, mesmos códigos.
Os Motores usam a mesma base da API 221b (https://221b-api.sherlocker.com.br/api/v1), mas autenticam via Authorization: Bearer slhk_…não via ?token=.

Formato base

Exemplo: uma requisição sem o header Authorization retorna 401:
Todo body de erro contém, no mínimo:
type é um identificador, não um endpoint: não faça dereferência dele em código de produção. Para decidir o que fazer programaticamente, use sempre o campo code.
O request_id em instance é o mesmo que você enviou no header opcional x-request-id (ou um UUID gerado pelo servidor, se você não enviou). Ele também é ecoado no header da resposta e no campo request_id dos bodies de sucesso.

Registro de códigos

Cada código tem uma página própria em /problems/<code>, válida para os dois motores. A coluna “quando acontece” indica os gatilhos em cada um:
O limite global da API é de 100 requisições por minuto por IP. Exceder o limite retorna 429 — honre o header Retry-After antes de tentar de novo.

Campos extras por tipo

Alguns códigos carregam campos adicionais legíveis por máquina além do shape base.

validation_errorerrors[]

Lista cada campo que falhou e a mensagem da restrição:
No Motor de Borderô, os mesmos errors[] reportam problemas field-level com as partes do multipart — file, xmls e cedente_cnpj (ex.: { "field": "file", "message": "No file provided" }, { "field": "cedente_cnpj", "message": "Invalid CNPJ format" }). Nesse caso nada é cobrado — no borderô, o débito só acontece após o parse bem-sucedido do CNAB.

insufficient_tokensrequired e balance

Informa quantos tokens a requisição exigia (required) e o saldo atual do workspace (balance). No Motor de CPF/CNPJ, required é o custo da análise; no Motor de Borderô, as entidades únicas do arquivo vezes o preço unitário. Os valores abaixo são ilustrativos — o preço está em definição durante o beta:
O saldo é gerenciado no app Sherlocker — veja Cobrança.

feature_not_enabledrequest_access_url

Aponta para a página de solicitação de acesso ao beta:

Tratando erros no código

Faça o branching pelo campo code — o tratamento é o mesmo nos dois motores. Regras práticas:
  • validation_error / bad_request: corrija a requisição. Se for reenviar um POST com conteúdo diferente, use uma Idempotency-Key nova (a mesma key com conteúdo diferente retorna 409).
  • idempotency_conflict com requisição em andamento: não reenvie o POST — consulte via GET (/analyses/{id} ou /operations/{id}) com o id da resposta 202 original.
  • server_error (e timeouts de rede): reenvie com a mesma Idempotency-Key, com back-off. Detalhes em Idempotência.

Relacionado

Idempotência

Como tratar 409, retries seguros e a janela de 24h

Autenticação

Chaves slhk_, header Bearer e as causas de 401/403

Cobrança

Débito de tokens, reembolso em failed e saldo