Errors

Sovera returns errors as application/problem+json, the format defined by RFC 9457. Every response, success or failure, also carries an X-Request-Id header you can quote when you contact support.

The problem+json shape

An error body has a stable set of fields. type and title describe the class of problem, status mirrors the HTTP status, detail explains this specific occurrence, instance points at the failing request, and requestId matches the X-Request-Id header.

403 Forbidden

{
  "type": "https://verify.lioncapventures.com/problems/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This key is not authorized for verify:document.",
  "instance": "/v1/verify/document",
  "requestId": "req_9f2a71c4"
}

Name
type
Type
string (URI)
Description
A URI identifying the problem class. Use it to branch in code rather than parsing title.
Name
title
Type
string
Description
A short, human-readable summary of the problem class.
Name
status
Type
integer
Description
The HTTP status code, repeated in the body for convenience.
Name
detail
Type
string
Description
A human-readable explanation specific to this occurrence.
Name
instance
Type
string
Description
A URI reference for the specific request that failed.
Name
requestId
Type
string
Description
The request identifier, matching the X-Request-Id response header.

Request IDs

Read X-Request-Id from every response and log it alongside your own request. When something goes wrong, that ID lets the Sovera team find the exact call.

Reading X-Request-Id

curl -i https://verify.lioncapventures.com/v1/verify/liveness \
  -H "Authorization: Bearer svk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"image":"<base64>"}' | grep -i x-request-id

Status codes

Name
400
Type
Bad Request
Description
The request body was malformed or failed validation.
Name
401
Type
Unauthorized
Description
The API key is missing or invalid. See Authentication.
Name
403
Type
Forbidden
Description
The key is valid but lacks the required scope for this endpoint.
Name
404
Type
Not Found
Description
The referenced resource, such as a session or consent record, does not exist.
Name
409
Type
Conflict
Description
An Idempotency-Key was reused with a different request body. See Idempotency.
Name
422
Type
Unprocessable Entity
Description
The request was well-formed but could not be processed, for example no face was detected.
Name
429
Type
Too Many Requests
Description
You are sending requests too quickly. Back off and retry.
Name
500
Type
Server Error
Description
Something failed on Sovera's side. Quote the requestId when you report it.

Branch on the type URI and the HTTP status, not on the title or detail strings, which are meant for humans and may be reworded.