Diagnostique pelo estado e pelo código estável
Conserve X-Request-Id, o ID da operação e o estado. Nunca registe a chave da API, o URL do destinatário,
o contacto, a imagem de prova ou o corpo em bruto do webhook. Alguns endpoints devolvem um code
estruturado, outros devolvem erros de validação ou um 401/403/404 vazio. Não assuma que todos os erros
partilham a mesma estrutura JSON e nunca baseie decisões no texto traduzido das mensagens.
| Código ou estado | Causa provável | Nova tentativa e ação corretiva |
|---|---|---|
| 401 | Credencial em falta, malformada, revogada ou expirada | Corrija a credencial; não repita sem alterações |
| 403 | Âmbito ou permissão da conta em falta | Verifique o âmbito da operação e o ambiente; atualize as credenciais após alterações de configuração |
| 404 | ID/ambiente errado ou acesso expirado/inválido | Verifique a leitura canónica autenticada e o ambiente |
| 429 | Limite de frequência/quota | Respeite Retry-After; espera exponencial com variação aleatória |
| 5xx / falha de transporte | Falha temporária do serviço/rede | Reutilize os IDs e o conteúdo exatos, limite as tentativas e inspecione o estado canónico após um resultado incerto |
returns_paused | Escritas de devolução temporariamente indisponíveis | Repita mais tarde com os mesmos IDs; as leituras continuam disponíveis |
idempotency_key_invalid | Chave de criação em falta/demasiado longa | Forneça uma chave estável não vazia, com um máximo de 160 caracteres |
idempotency_conflict | Chave reutilizada para uma operação diferente | Recupere o pedido original ou utilize uma chave para uma operação verdadeiramente nova |
event_id_invalid | UUID em falta/vazio | Gere e guarde um UUID por evento |
occurred_at_invalid | Data/hora futura do evento | Corrija o relógio/data e hora; conserve a hora real da ocorrência |
return_not_eligible | Estado de saída não permite este tipo de devolução | A devolução de cliente exige Delivered; a RTS por entrega falhada exige DeliveryAttempted |
return_state_conflict | Transição inválida, dependência de prova ou evento em conflito | Leia o estado canónico e os requisitos de prova; corrija antes de repetir |
return_conflict | Devolução concorrente/restrição de identificador | Leia a devolução atual; não duplique trabalho físico |
return_origin_invalid, return_destination_invalid | Instantâneo em falta/inválido | Forneça campos e coordenadas de endereço confirmado válidos |
return_event_invalid | Dados de evento inválidos | Corrija os dados com a referência da API |
return_pickup_confirmation_not_allowed | Acesso à recolha não permitido no estado atual | Inspecione o estado de autorização/entrega física antes de emitir uma nova ligação |
return_proof_asset_missing | A referência não aponta para um ficheiro de devolução enviado | Envie primeiro o PNG com devolução/prova/tipo correspondentes; utilize a referência devolvida |
return_proof_invalid, proof_image_invalid | Imagem ou campos de prova inválidos | Corrija o método, a finalidade, as dimensões, o tamanho e a data/hora |
return_proof_conflict | UUID de prova reutilizado com conteúdo diferente | Repita a prova idêntica; nunca substitua provas imutáveis |
return_destination_required | A política RTS exige um destino | Forneça o destino acordado do remetente/comerciante |
Problemas de integração comuns
A chave copiada começa por [object Object]: copie novamente a credencial da consola.
Uma chave não contém ícones, marcação nem texto de apresentação final. Configure o valor completo em bruto.
O estado da entrega não avançou após submeter a prova: inspecione a sincronização da prova.
O âmbito delivery:proof é separado de delivery:events. Uma prova falhada bloqueia
o evento de conclusão dependente. Corrija a configuração e repita a operação original
com os mesmos identificadores.
O meu correio eletrónico corresponde, mas a ligação do destinatário falha: verifique se o contacto canónico da expedição está correto e se o contacto da conta está verificado. Um contacto utilizado apenas para confirmação de endereço não altera a titularidade da expedição. O seguimento público comprova o progresso, não a autorização do destinatário.
Não existe opção de devolução: a entrega tem de estar associada e canonicamente Delivered antes de poder iniciar uma devolução de cliente.
URL de prova de devolução rejeitado: envie um PNG real através da API de ficheiros de devolução. Uma assinatura em texto ou um URL arbitrário do comerciante não satisfaz este contrato.
A assinatura do webhook falha: conserve os bytes em bruto, verifique o segredo correto da subscrição, confirme a atualidade da data/hora e evite voltar a serializar o JSON. Consulte o guia prático de webhooks.