Formato do erro
Nas chamadas com chave de API, erros de validação, autenticação, permissão, recurso inexistente e limite trazem um código estável e o identificador da requisição:
Erros de validação mantêm também a lista por campo, como
{"email": ["Informe um e-mail válido."]}. Algumas operações ainda respondem só com detail; trate a ausência de code como erro genérico do status HTTP.
Identificador da requisição
Toda resposta traz o headerX-Request-Id. Ao falar com o suporte, envie esse valor: ele localiza a requisição nos registros da sinnu. Se a sua chamada enviar X-Request-Id, o mesmo valor volta na resposta.
Limite por chave
A autenticação por chave aplica 100 requisições por minuto, por chave. Distribua consultas ao longo do tempo e prefira webhooks para acompanhar mudanças de pagamento.Timeout não determina o resultado
Uma falha de rede pode ocorrer depois de o servidor receber a solicitação. Antes de reenviar uma criação ou um estorno, consulte o recurso e confira se a operação já foi aplicada. O SDK atual não oferece retentativas automáticas nem uma opção de idempotência para criar links. Não acrescente headers de idempotência esperando um comportamento que o contrato não declara.O que registrar
Guarde método, caminho, status HTTP, horário, identificador do recurso e oX-Request-Id da resposta. Remova Authorization, segredos de webhook e dados pessoais dos registros enviados ao suporte.
No SDK, falhas HTTP geram erros tipados. Falhas de rede podem manter o erro original de fetch e precisam de tratamento separado.