Nigeria

Error handling

Nigeria 🇳🇬 KYC services can return three different response forms depending on the layer that originates the error. Below are the three forms and when each applies.

1. Service envelope (verification success and errors)

Success responses and verification errors use the standard service envelope:

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

In this family of services, serviceResultCode reflects the HTTP status code of the response: 200 in case of success and 400/404 in query errors (for example, a nonexistent BVN). No es 0 in case of success. The HTTP status code of the response matches the value of serviceResultCode.

serviceResultCode	Description	HTTP code
200	The service execution was successful.	200
400	The request was rejected (invalid data, expired session…).	400
404	The queried resource was not found.	404
500	Special case: the service is unavailable or its response could not be interpreted.	502

2. Validation and routing errors (application/problem+json)

Errors generated by the platform itself before processing the query follow the format RFC 7807 (Content-Type: application/problem+json):

Field	Type	Description
status	integer	Response HTTP status code.
title	string	Descriptive error title.
detail	string	Error description.
type	string	Reference URI of the HTTP status code.
errors	array	List of validation errors. Only present when applicable.

Cases in which this form is returned:

HTTP code	Case
400	Field validation error or malformed body.
404	Unknown route.
405	HTTP method not supported by the route.

Validation error example:

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

Any request POST, PUT or PATCH with the empty body returns 400 with the error request body should not be empty, before routing even takes place. This behavior is common to the entire platform.

3. Authentication errors (gateway)

When authentication fails, the request is rejected by the gateway before reaching the service. These responses are the default responses of AWS API Gateway and do not use the envelope serviceResultCode:

HTTP code	Response body	Case
401	{"message": "Unauthorized"}	API Key missing or invalid.
403	{"Message": "User is not authorized to access this resource with an explicit deny"}	Valid API Key but without access to the resource.

The capitalization of the field differs between both responses (message in the 401, Message in the 403): they are the default bodies of AWS API Gateway.