> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria.md).

# Nigeria

### Error handling

Nigeria KYC services 🇳🇬 can return **three distinct 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:

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

{% hint style="info" %}
In this service family, `serviceResultCode` **reflects the HTTP response code**: `200` in the event of success and `400`/`404` in query errors (for example, a non-existent BVN). **No** is `0` in the event of success. The HTTP response code matches the value of `serviceResultCode`.
{% endhint %}

| serviceResultCode | Description                                                                            | HTTP code |
| ----------------- | -------------------------------------------------------------------------------------- | --------- |
| 200               | The service execution was successful.                                                  | 200       |
| 400               | The request was rejected (invalid data, expired session…).                             | 400       |
| 404               | The requested 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 request** follow the format **RFC 7807** (`Content-Type: application/problem+json`):

| Field    | Type    | Description                                              |
| -------- | ------- | -------------------------------------------------------- |
| `status` | integer | HTTP response code.                                      |
| `title`  | string  | Descriptive error title.                                 |
| `detail` | string  | Error description.                                       |
| `type`   | string  | HTTP code reference URI.                                 |
| `errors` | array   | List of validation errors. Present only 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:

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

{% hint style="warning" %}
Any request `POST`, `PUT` or `PATCH` with the **empty body** returns `400` with the error `request body should not be empty`, even before routing. This behavior is common across the entire platform.
{% endhint %}

#### 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"}`                                                         | Missing or invalid API Key.                  |
| 403       | `{"Message": "User is not authorized to access this resource with an explicit deny"}` | Valid API Key but no access to the resource. |

{% hint style="info" %}
The field capitalization differs between both responses (`message` in the `401`, `Message` in the `403`): they are the default bodies of AWS API Gateway.
{% endhint %}