Responses & Errors

The standard Sovera response envelope, error format, status codes and trace correlation shared by every endpoint.

Read this first

Every Sovera API response — success or error — shares the same envelope. Each endpoint page documents only its data payload; the wrapper described here is added consistently across the whole API.

Base URL

Staging:

https://api.sandbox.sovera.io/cards

Production:

https://api.sovera.io/cards

Every path carries the contract version as a /v2/ segment — for example https://api.sovera.io/cards/v2/wallet/credits/. The same v2 echoes back in meta.version.

Success Envelope

Successful responses (2xx) wrap the resource in data:

{
  "success": true,
  "data": {
    "userId": "8f3c…",
    "isActive": true,
    "status": "ACTIVE"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

success — true for 2xx.
data — the resource payload. The shape per endpoint is documented on each page.
meta.timestamp — ISO‑8601 UTC of the response.
meta.version — API contract version (v2).
meta.traceId — correlation id for this request (see Trace correlation).

Reads (GET) and updates (PUT/PATCH) return 200 OK; resource creation (POST) returns 201 Created.

Error Envelope

Errors (4xx / 5xx) replace data with an errors array:

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "The Email field is required.", "field": "email" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

errors[].code — machine-readable code (see the table below).
errors[].message — human-readable description.
errors[].field — present on validation errors; the offending field in camelCase.

Validation errors

A request that fails field validation returns one item per invalid field:

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "The Email field is required.", "field": "email" },
    { "code": "VALIDATION_ERROR", "message": "The Occupation field is required.", "field": "occupation" },
    { "code": "VALIDATION_ERROR", "message": "The CountryOfOperations field is required.", "field": "countryOfOperations" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Status Codes

HTTP	`code`	Meaning
400	`BAD_REQUEST`	Malformed request (not a field-validation failure).
401	`UNAUTHORIZED`	The API key is missing, invalid, or expired.
403	`FORBIDDEN`	Insufficient permissions for the action.
404	`NOT_FOUND`	The requested resource does not exist.
409	`CONFLICT`	Conflicts with the current state of the resource.
422	`VALIDATION_ERROR`	Well-formed request that fails field validation or a business rule.
429	`TOO_MANY_REQUESTS`	Rate limit exceeded.
500	`INTERNAL_SERVER_ERROR`	Unexpected server error.
502 / 503 / 504	`BAD_GATEWAY` / `SERVICE_UNAVAILABLE` / `GATEWAY_TIMEOUT`	Upstream unavailable or timed out.

Trace Correlation

Every response carries a traceId (a UUID v4) in meta.traceId and in the x-trace-id response header.

Omit x-trace-id on the request and Sovera generates one for you.
Send your own x-trace-id (must be a valid UUID v4) to correlate the call with your own logs; it is echoed back unchanged.
Sending a value that is not a UUID v4 returns 422.

curl https://api.sandbox.sovera.io/cards/v2/managed/end/users/8f3c… \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "x-trace-id: 73a5d32a-f92c-41eb-af8d-d7c6435f9a06"

Always include the traceId when contacting Sovera support about a specific request.

Authentication

Every call must send the API key in the x-api-key header over HTTPS. A missing key returns 401. See Introduction for how to obtain sandbox keys.