> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Result Codes

> What `status` and `result.code` mean when a verification reaches a final status, and what to do for each code.

A verification that reaches a final status reports it in two fields.

* `status` is `completed` or `failed`.
  * `completed`: the provider finished the check, with or without user data.
  * `failed`: the verification stopped before the provider finished the check.
* `result.code` is what you branch on. The codes are the same for every connection.

```json theme={null}
{
  "verificationId": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
  "status": "completed",
  "result": {
    "code": "RECORD_NOT_FOUND",
    "message": "No record was found for this CPF."
  },
  "endedAt": "2026-11-19T09:01:05.120Z"
}
```

`result.message` is a short description of the code, for developers. Do not branch on it or show it to users. Write the text your users see from `result.code`.

To update an integration that reads `status` alone, see [Migrate to Result Codes](https://docs.hopae.com/v2/guides/migration/result-codes).

## Codes

| Code | Status | Meaning | Suggested action |
| :- | :- | :- | :- |
| `RECEIVED` | `completed` | The provider finished the check and userinfo is ready. On a `match` connection, this code applies even when the comparison did not match. | Read userinfo and decide. On a `match` connection, check `match.matched`. |
| `RECORD_NOT_FOUND` | `completed` | The source was queried and has no record for the submitted values. | Ask the user to check the input. If it is correct, offer another method. |
| `CREDENTIAL_INVALID` | `completed` | The ID document or eID cannot be used. It is expired, suspended, revoked, or failed validation. | Decline, or ask for another document. |
| `MINOR_NOT_ALLOWED` | `completed` | The user is younger than the minimum age for this connection. | Decline. A retry gives the same result. |
| `LOA_NOT_MET` | `completed` | The user signed in below the level this connection requires, so no data is returned. | Offer another method, or ask the user to sign in at a higher level. |
| `INVALID_USER_DATA` | `failed` | The provider rejected the submitted input. | Ask the user to correct the input and start a new verification. |
| `IMAGE_INVALID` | `failed` | The submitted selfie or document image cannot be used. | Ask the user to retake the photo. |
| `EID_NOT_ELIGIBLE` | `failed` | The user cannot use this eID, for example because they have no account. | Offer another method. A retry gives the same result. |
| `LOGIN_FAILED` | `failed` | The user failed to sign in at the provider. | Let the user retry. If it repeats, offer another method. |
| `USER_CANCELLED` | `failed` | The user cancelled at the provider. | Return the user to the method selection. Do not restart automatically. |
| `SESSION_EXPIRED` | `failed` | The user did not finish within the provider's time limit. | Start a new verification. |
| `CLIENT_CANCELLED` | `failed` | You cancelled with [Cancel Verification](https://docs.hopae.com/v2/api-reference/verifications/cancel-verification.md). | Nothing. |
| `PROVIDER_CONFIGURATION_ERROR` | `failed` | The provider rejected the credentials or settings registered for this connection. | Check the connection's settings in Console. If Hopae manages them, contact support. |
| `PROVIDER_UNAVAILABLE` | `failed` | The provider did not respond, is down, or is limiting requests. | Retry later, or offer another method. |
| `PROVIDER_ERROR` | `failed` | The provider returned an error that Hopae could not classify. | Retry once. If it repeats, contact support with the `verificationId`. |
| `INTERNAL_ERROR` | `failed` | An error on the Hopae side. | Offer another method and contact support with the `verificationId`. |

More codes can be added. Only `RECEIVED` gives user data, so treat a code you do not know as not verified and offer the user another method.

Support is at [support@hopae.com](mailto:support@hopae.com).

> [!NOTE]
>
> `SESSION_EXPIRED` is the provider's own time limit. A verification past its `expiresAt` is deleted and returns `404` instead. See [Expiry](https://docs.hopae.com/v2/guides/verifications/verification-flow.md#expiry).

## Where the code appears

| Where | Field |
| :- | :- |
| [Get Verification](https://docs.hopae.com/v2/api-reference/verifications/get-verification.md) | `result.code`, `result.message` |
| [OIDC](https://docs.hopae.com/v2/guides/oidc-integration.md) error redirect | `result_code`, and the message in `error_description` |
| [Webhooks](https://docs.hopae.com/v2/guides/webhook-signing.md) | `data.result.code`, `data.result.message` |

Userinfo is available only when the code is `RECEIVED`. Any other code answers `409 SESSION_INVALID_STATUS_TRANSITION`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.