# Códigos de erro da API de parceiros

Catálogo 1.2.0 · Revisto em 2026-11-04.

Estes são códigos próprios da EDPay, independentes do status HTTP. A resposta usa `error.code`; consulte também `meta.request_id` ao pedir suporte. Códigos da área autenticada e do Payment Master não são publicados aqui.

| Código | HTTP | Significado | Retry | Acção indicada |
| --- | ---: | --- | --- | --- |
| `account_currency_mismatch` | 409, 422 | A moeda do pagamento ou link não corresponde à moeda-base configurada para a conta. | no | Use a moeda-base MZN, USD ou EUR da conta. O valor de cobrança móvel é convertido para MZN pelo fluxo de pagamento. |
| `account_not_active` | 403 | A conta está suspensa, encerrada ou não pode iniciar pagamentos. | no | Contacte o administrador da conta para reactivar a conta; não repita pagamentos enquanto estiver suspensa. |
| `account_required` | 403 | A chave/API principal não está vinculada a uma conta para esta operação. | no | Use uma credencial vinculada a uma conta activa. |
| `amount_out_of_range` | 422 | O montante convertido excede o intervalo suportado pelo sistema. | no | Reduza o montante ou use uma combinação de montante e moeda dentro dos limites suportados. |
| `conflict` | 409 | O pedido conflita com o estado actual do recurso e não tem um código mais específico. | no | Leia a mensagem e consulte o estado actual antes de repetir uma escrita. |
| `customer_not_found` | 404 | O cliente não existe no âmbito da conta e ambiente autorizados. | no | Confirme o ID e o âmbito de conta/ambiente antes de repetir. |
| `environment_required` | 403 | A credencial não está vinculada a um ambiente de conta activo compatível. | no | Use uma API key vinculada ao ambiente sandbox ou production pretendido. |
| `fee_policy_unavailable` | 409 | Não existe uma política de comissão utilizável para calcular o valor líquido da transacção. | no | Configure ou corrija a política de comissão da conta; só depois reenvie a operação com uma chave de idempotência apropriada. |
| `forbidden` | 403 | A operação não é permitida para esta identidade ou recurso. | no | Confirme a identidade, o scope e a permissão para a conta/ambiente. Repetir sem corrigir autorização não terá efeito. |
| `fx_quote_unavailable` | 503 | Não foi possível calcular uma cotação FX válida para este pedido. | conditional | Confirme a disponibilidade da tabela de câmbio e reutilize a mesma chave de idempotência se o pedido for uma escrita. |
| `fx_rate_unavailable` | 503 | Não existe taxa activa para o par de moedas solicitado. | conditional | Configure ou active uma taxa para o par; não assuma uma cotação por defeito. |
| `idempotency_conflict` | 409 | A chave de idempotência já foi usada com dados ou operação diferentes. | no | Use a mesma chave apenas com o mesmo pedido. Se a intenção for uma nova operação, resolva o conflito e use uma chave nova. |
| `idempotency_key_required` | 400 | Falta um cabeçalho Idempotency-Key válido na operação de escrita. | no | Corrija a entrada, credencial, permissão ou estado indicado. Não repita sem alterar a causa. |
| `insufficient_scope` | 403 | A chave não possui o scope exigido pela operação. | no | Crie ou seleccione uma chave com o scope exigido pelo endpoint. |
| `internal_error` | 500 | O serviço encontrou um erro interno ou não conseguiu concluir uma operação local. | conditional | Consulte meta.request_id e o estado da operação antes de repetir. Para escritas, reutilize a mesma chave de idempotência. |
| `invalid_amount` | 400, 422 | O montante deve ser um número inteiro positivo em unidades menores da moeda indicada. | no | Envie um montante positivo na unidade menor correspondente à moeda do pedido. |
| `invalid_currency` | 400 | A moeda não tem exactamente três letras ASCII. | no | Envie um código de moeda ASCII de três letras; links aceitam MZN, USD ou EUR quando coincide com a moeda-base da conta. |
| `invalid_description` | 422 | A descrição está vazia ou excede o limite aceite. | no | Envie uma descrição não vazia dentro do limite de tamanho. |
| `invalid_expiration` | 422 | A data de expiração não é válida, não tem fuso horário explícito ou já passou. | no | Envie uma data futura válida com fuso horário explícito. |
| `invalid_input` | 422 | Um ou mais campos de entrada não cumprem as regras da operação. | no | Corrija os campos rejeitados segundo a resposta e reenvie. |
| `invalid_method` | 422 | O método de pagamento deve ser emola ou mpesa. | no | Use emola ou mpesa. |
| `invalid_phone` | 422 | O número de telefone não é válido para o método de pagamento seleccionado. | no | Corrija o telefone para o formato aceito pelo método seleccionado. |
| `invalid_reference` | 422 | A referência não cumpre o formato permitido. | no | Envie uma referência alfanumérica dentro do limite documentado. |
| `invalid_request` | 400, 422 | O pedido não é válido ou os dados do pagamento não passaram validação. | no | Corrija os campos ou o formato do pedido antes de repetir. |
| `invalid_response` | 500 | Um handler produziu uma resposta que não é JSON válido. | conditional | Correlacione meta.request_id e consulte o estado antes de repetir uma escrita; a resposta inválida não confirma o resultado. |
| `invalid_webhook_events` | 400 | A lista contém tipos de evento não suportados ou repetidos. | no | Envie uma lista não vazia, sem repetições, com apenas eventos suportados. |
| `invalid_webhook_url` | 400 | URL de webhook inválido. | no | Use um URL HTTPS público sem credenciais, query string ou fragmento. |
| `method_not_allowed` | 405 | O método HTTP não é aceite para esta rota. | no | Use o método HTTP indicado para essa rota. |
| `not_found` | 404 | A rota ou o recurso solicitado não foi encontrado. | no | Confirme o caminho e o identificador; recursos de outra conta/ambiente não são acessíveis. |
| `payload_too_large` | 413 | O corpo do pedido excede o limite de tamanho permitido. | no | Reduza o corpo do pedido antes de reenviar. |
| `payment_not_found` | 404 | O pagamento não existe ou não está acessível no escopo actual; na rota interna, nenhuma cobrança corresponde à chave privada recebida. | no | Confirme o ID de pagamento e a conta/ambiente seleccionados. |
| `payments_unavailable` | 503 | O processamento de pagamentos não está configurado ou disponível neste momento. | conditional | Aguarde o processamento ficar disponível. Reenvie a mesma operação apenas com a mesma chave de idempotência. |
| `production_payments_disabled` | 403 | A criação de cobranças em produção está desactivada por configuração da plataforma. | no | Use o ambiente sandbox. Não tente contornar o bloqueio nem activar Produção antes da verificação de callbacks, reconciliação e ledger. |
| `rate_limited` | 429 | O limite de pedidos foi atingido. | yes_after_delay | Aguarde o cabeçalho Retry-After quando presente. Em operações de escrita, repita exactamente o mesmo pedido com a mesma chave de idempotência. |
| `reference_conflict` | 409 | A referência fornecida já está a ser usada neste ambiente. | no | Escolha uma referência não utilizada. Confirme que a operação anterior não foi criada antes de reenviar. |
| `request_error` | evento | O pedido foi rejeitado com um status 4xx sem um código mais específico definido pelo normalizador. | no | Corrija o método, caminho ou dados conforme o status e a resposta. |
| `request_in_progress` | 409 | Outro pedido com esta mesma chave de idempotência ainda está em curso. | yes_after_delay | Aguarde a operação terminar e consulte/reenvie com a mesma chave de idempotência; não crie outra operação. |
| `service_unavailable` | 503 | Uma dependência ou operação de armazenamento está temporariamente indisponível. | conditional | Aguarde a dependência ficar saudável. Para escritas, reutilize a mesma chave e consulte o estado antes de iniciar outra operação. |
| `unauthorized` | 401 | A autenticação está ausente, inválida, expirada ou revogada. | no | Confirme a credencial e a sessão; não repita até corrigir autenticação ou expiração. |
| `unsupported_currency` | 422 | A operação não suporta a moeda enviada. Pagamentos, cotações e links aceitam MZN, USD ou EUR; links exigem coincidência com a moeda-base da conta. | no | Use MZN, USD ou EUR e crie payment links na moeda-base da conta. |
| `unsupported_currency_pair` | 422 | O par de moedas não é suportado; apenas conversões entre MZN e USD/EUR estão definidas. | no | Use MZN↔USD ou MZN↔EUR conforme a tabela activa. |
| `unsupported_media_type` | 415 | O endpoint requer conteúdo JSON e não aceita o Content-Type enviado. | no | Envie JSON e defina Content-Type: application/json. |
| `validation_error` | 422 | Os dados foram recebidos, mas não passaram validação de domínio. | no | Leia error.details, corrija os campos inválidos e reenvie. |
| `webhook_delivery_not_found` | 404 | A entrega não existe no tenant e ambiente da chave. | no | Confirme o identificador usando a mesma conta e ambiente da API key. |
| `webhook_delivery_retry_not_allowed` | 409 | A entrega não pode ser repetida enquanto o endpoint estiver desactivado. | no | Active novamente um endpoint por meio de um novo registo e confirme a configuração antes de criar nova entrega. |
| `webhook_endpoint_not_found` | 404 | O endpoint não existe no tenant e ambiente da chave. | no | Confirme o identificador usando a mesma conta e ambiente da API key. |
| `webhook_secrets_unavailable` | 503 | O serviço não consegue cifrar o segredo do endpoint. | no | Configure PLATFORM_WEBHOOK_ENCRYPTION_KEY e publique a versão com essa configuração. |
| `worker_interrupted` | evento | O worker foi interrompido durante uma tentativa; o resultado é desconhecido e não confirma sucesso nem falha final. | conditional | Consulte os eventos e reconcilie com o Master/provider antes de reenviar ou criar outra cobrança. |

O JSON desta mesma lista está em [`error-codes.json`](error-codes.json).