/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 headerAuthorization retorna 401:
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_error — errors[]
Lista cada campo que falhou e a mensagem da restrição:
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_tokens — required 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:
feature_not_enabled — request_access_url
Aponta para a página de solicitação de acesso ao beta:
Tratando erros no código
Faça o branching pelo campocode — 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 umaIdempotency-Keynova (a mesma key com conteúdo diferente retorna409).idempotency_conflictcom requisição em andamento: não reenvie o POST — consulte viaGET(/analyses/{id}ou/operations/{id}) com oidda resposta 202 original.server_error(e timeouts de rede): reenvie com a mesmaIdempotency-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/403Cobrança
Débito de tokens, reembolso em
failed e saldo