Respostas e erros
Os recursos da API V1 usam JSON e frequentemente retornam success, data, message e, em listas, meta e links. Nem todos os endpoints possuem exatamente o mesmo contrato: confira o recurso correspondente.
Códigos que precisam de tratamento
| HTTP | Significado habitual | Ação recomendada |
|---|---|---|
200 |
Consulta/atualização concluída | Verifique success e os dados |
201 |
Recurso criado | Registre o identificador retornado |
401 |
Credencial ausente ou inválida | Revise o token e sua vigência |
403 |
Ação não autorizada | Revise a permissão da integração |
404 |
Recurso não encontrado | Confirme ID, código e empresa do token |
422 |
Validação de dados | Corrija os campos apontados |
429 |
Limite de tráfego, se aplicado | Respeite eventual Retry-After |
5xx |
Falha do serviço | Registre detalhes não sensíveis e faça retentativa controlada |
Os códigos acima descrevem o tratamento recomendado, não garantem que todas as rotas retornem cada um deles.
Evite escritas duplicadas
Quando uma conexão cai após um POST ou PUT, a operação pode ter sido concluída. Consulte o registro antes de reenviar. Uma chave de idempotência geral ainda não está documentada para toda a V1.
Nunca registre Authorization, senhas, informações de cartão ou documentos completos nos logs.