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