Nigéria

Tratamento de erros

Os serviços KYC da Nigéria 🇳🇬 podem retornar três formas distintas de resposta dependendo da camada que origina o erro. A seguir, são descritas as três formas e quando cada uma se aplica.

1. Envelope do serviço (sucesso e erros da verificação)

As respostas de sucesso e os erros da verificação usam o envelope padrão do serviço:

{
  "serviceResultCode": 200,
  "serviceResultLog": "Success",
  "serviceTime": "151",
  "serviceTransactionId": "08ac9699-dc9e-4cdc-81d7-264f71838309",
  "data": { }
}

Nesta família de serviços, serviceResultCode reflete o código HTTP da resposta: 200 em caso de sucesso e 400/404 em erros da consulta (por exemplo, um BVN inexistente). Não es 0 em caso de sucesso. O código HTTP da resposta coincide com o valor de serviceResultCode.

serviceResultCode	Descrição	Código HTTP
200	A execução do serviço foi bem-sucedida.	200
400	A solicitação foi rejeitada (dados inválidos, sessão expirada…).	400
404	O recurso consultado não foi encontrado.	404
500	Caso especial: o serviço não está disponível ou sua resposta não pôde ser interpretada.	502

2. Erros de validação e de roteamento (application/problem+json)

Os erros gerados pela própria plataforma antes de processar a consulta seguem o formato RFC 7807 (Content-Type: application/problem+json):

Campo	Tipo	Descrição
status	integer	Código HTTP da resposta.
title	string	Título descritivo do erro.
detail	string	Descrição do erro.
type	string	URI de referência do código HTTP.
errors	array	Lista de erros de validação. Presente apenas quando aplicável.

Casos em que essa forma é retornada:

Código HTTP	Caso
400	Erro de validação de campos ou corpo malformado.
404	Rota desconhecida.
405	Método HTTP não suportado pela rota.

Exemplo de erro de validação:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": ["bvn is required"]
}

Qualquer solicitação POST, PUT ou PATCH com o corpo vazio retorna 400 com o erro o corpo da solicitação não deve estar vazio, antes mesmo do roteamento. Esse comportamento é comum a toda a plataforma.

3. Erros de autenticação (gateway)

Quando a autenticação falha, a solicitação é rejeitada pelo gateway antes de chegar ao serviço. Essas respostas são as respostas padrão do AWS API Gateway e não usam o envelope serviceResultCode:

Código HTTP	Corpo da resposta	Caso
401	{"message": "Unauthorized"}	API Key ausente ou inválida.
403	{"Message": "User is not authorized to access this resource with an explicit deny"}	API Key válida, mas sem acesso ao recurso.

A capitalização do campo difere entre ambas as respostas (message no 401, Message no 403): são os corpos padrão do AWS API Gateway.