Errors

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.

Error response shape

{
  "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:

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

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_required`	400	Tried to create a verification without a valid pre-existing consent.	Create a consent via `POST /consents` first. See Consents.
`unauthorized`	401	API key is missing or invalid.	Check the key in the Developers section of 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.
`daily_verification_limit_exceeded`	429	More than 2 verification attempts on the same identifier within 24 hours.	Try again after midnight UTC. See Rate Limits.
`rate_limit_exceeded`	429	More than 120 requests in 60 seconds across all endpoints.	Back off and retry after the `X-RateLimit-Reset` timestamp.

Examples by category

400 — Validation

{
  "error": {
    "code": "validation_error",
    "message": "Invalid input for consent creation.",
    "details": "Field 'ip_address' is required."
  }
}

401 — Authentication

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

404 — Not found

{
  "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."
  }
}

429 — Rate limited

{
  "error": {
    "code": "daily_verification_limit_exceeded",
    "message": "Try again tomorrow. You have reached the daily verification limit for this identifier.",
    "details": "Maximum 2 verification attempts per identifier per day. Limit resets at midnight UTC."
  }
}

Where to look next

For per-endpoint error responses with full examples, see the API Reference.
For rate limit headers and recommended retry behavior, see Rate Limits.