---
updatedAt: 2026-10-28T18:23:33.000Z
agentTools:
  projectIndex: https://developers.burodeingresos.com/llms.txt
---

# Errors

Standard error response shape and the full list of error codes the Buró de Ingresos API can return.

Every error response uses a standard shape. Use the `code` field to branch your logic; the `message` and `details` fields are human-readable and may evolve.

<br />

<br />

## Error response shape

```json
{
  "error": {
    "code": "verification_not_found",
    "message": "No verification found with the specified ID.",
    "details": "The verification_id b5e7c9a1-3d28-4f6e-8a0c-e1d4f2b7a953 does not correspond to an existing verification."
  }
}
```

Authentication errors (`401`) use a flatter shape:

```json
{
  "error": "Unauthorized",
  "message": "Invalid X-API-Key"
}
```

<br />

## Error codes

| Code                            | HTTP | When it's returned                                                                                            | What to do                                                                                                       |
| :------------------------------ | :--- | :------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------- |
| `validation_error`              | 400  | Payload is missing a required field or has an invalid format.                                                 | Fix the payload and retry. The `details` field names the offending field.                                        |
| `consent_not_found`             | 400  | `POST /verifications` without `ip_address`, and no consent exists for this identifier.                        | Send `ip_address` with the verification. See [Consents](https://developers.burodeingresos.com/docs/consents).    |
| `consent_expired`               | 400  | `POST /verifications` omits `ip_address`, and the most recent legacy consent for this identifier has expired. | Send `ip_address` with the verification to record a new consent.                                                 |
| `privacy_notice_not_configured` | 400  | `ip_address` was sent, but your company has no privacy notice on file.                                        | Contact support to register your privacy notice, then retry.                                                     |
| `unauthorized`                  | 401  | API key is missing or invalid.                                                                                | Check the key in the **Developers** section of [console.burodeingresos.com](https://console.burodeingresos.com). |
| `profile_not_found`             | 404  | `GET /profile/{identifier}` has no data for this identifier.                                                  | Confirm the verification completed and the `entities` array contained `profile`.                                 |
| `business_profile_not_found`    | 404  | `GET /business-profile/{identifier}` has no data.                                                             | Confirm the verification completed and the `entities` array contained `business_profile`.                        |
| `employment_history_not_found`  | 404  | `GET /employments/{identifier}` has no data.                                                                  | Confirm the verification yielded `employment` data.                                                              |
| `employment_files_not_found`    | 404  | `GET /employment-files/{identifier}` has no data.                                                             | Confirm the verification yielded `employment_files` data.                                                        |
| `verification_not_found`        | 404  | The `verification_id` does not exist or was already deleted.                                                  | Double-check the ID; if you deleted it, the record is gone.                                                      |
| `bulk_verification_not_found`   | 404  | The `bulk_id` does not exist.                                                                                 | Double-check the ID.                                                                                             |
| `rate_limit_exceeded`           | 429  | More than 120 requests in 60 seconds across all endpoints.                                                    | Back off and retry after the `X-RateLimit-Reset` timestamp.                                                      |

<br />

## Examples by category

### 400 — Validation

```json
{
  "error": {
    "code": "validation_error",
    "message": "Invalid input for verification creation.",
    "details": "Field 'phone' must be in E.164 format."
  }
}
```

### 401 — Authentication

```json
{
  "error": "Unauthorized",
  "message": "Invalid X-API-Key"
}
```

### 404 — Not found

```json
{
  "error": {
    "code": "profile_not_found",
    "message": "No profile data found for the specified identifier.",
    "details": "This may be because no successful verification has been completed for this identifier, or the verification did not yield profile data."
  }
}
```

###

## Where to look next

* For per-endpoint error responses with full examples, see the [API Reference](https://developers.burodeingresos.com/reference).
* For rate limit headers and recommended retry behavior, see [Rate Limits](https://developers.burodeingresos.com/docs/rate-limits).