Como interpretar os erros da API?

O corpo de um erro depende de quem respondeu, e a API tem mais de um formato. Três regras cobrem a maior parte dos casos.

Três regras práticas

• Ramifique em code, nunca no texto de error. O code é estável, em MAIÚSCULAS_COM_UNDERSCORE. O texto de error serve para exibir e pode mudar.
• Nem toda resposta traz code. Erros de autenticação e permissão trazem type. Erros de validação de schema e de limite de requisições não têm código: trate pelo status HTTP.
• Um code desconhecido não pode quebrar o seu parser. A lista cresce. Caia no tratamento genérico do status.

Em erro de validação, leia error para exibir e use details apenas se existir.

O que cada status significa

• 400: corpo ou parâmetro inválido.
• 401: chave ausente, inválida, inativa ou expirada, ou rota que não aceita chave.
• 403: escopo insuficiente ou recurso não habilitado para a conta.
• 404: recurso inexistente ou de outra conta. A API não distingue os dois casos, de propósito.
• 409: conflito, geralmente duplicidade em campo único.
• 413: corpo grande demais.
• 422: corpo válido, mas a operação não pode ser executada no estado atual.
• 429: limite de requisições.
• 500: erro interno ou serviço externo sem resposta. O code indica qual.
• 503: indisponibilidade temporária. O Retry-After, quando vem, diz quando repetir.

Sucesso também tem pegadinha

A maioria das criações responde 200. A criação de cobrança internacional e a de cartão respondem 201. Trate a faixa 2xx inteira como sucesso.

E se aparecer 502 ou 504?

A Dotfy não responde esses códigos. Quando aparecem, vêm da rede no caminho, como uma página HTML sem JSON, e o desfecho é desconhecido. Numa operação que cria algo, consulte antes de repetir.

Recebi 403 com a chave certa

Alguns recursos, como cartão e boleto, são liberados por conta. Isso não se resolve por código: é uma configuração da conta. Fale com o seu contato na Dotfy.

Os valores possíveis de code estão na página de cada endpoint, na referência da API.