Your first API call

This tutorial takes one request apart, so you can tell a working integration from a broken one by reading the response alone.

The request

curl -i https://api.essence.digital/api/v1/vaults \
  -H "Authorization: Bearer $ESSENCE_ACCESS_TOKEN"

• https://api.essence.digital is the API origin. Every path is versioned: /api/v1/….
• Authorization: Bearer … carries your access token (see Authentication). Without it, every protected path answers 401.

Reading the response headers

These headers come back on every response, success or failure:

Header	Example	What it tells you
x-correlation-id	7234a82d-f665-4c67-b4a0-cfd5f9c09f5f	The ID of this request across every service it touched. Quote it when you contact support
x-ratelimit-limit	100	Requests allowed in the current window
x-ratelimit-remaining	99	Requests left in the window
x-ratelimit-reset	1790370832	When the window resets, in Unix seconds

When x-ratelimit-remaining reaches 0, further requests get 429 Too Many Requests until the reset time. Back off until then rather than retrying at once.

Telling the failures apart

Status	Body	Meaning	What to do
401	empty, with WWW-Authenticate: Bearer	No token, or the token is invalid or expired	Send a valid token, or refresh it
403	problem document	Your token is valid but may not do this	Check the permissions granted to the token
404	problem document or empty	No such path, or no such resource	Check the version segment and the ID
400	problem document with validationErrors	The request body failed validation	Fix the fields it names
429	problem document	Rate limit reached	Wait for x-ratelimit-reset

A 401 and a 404 are how you tell a wrong address from missing credentials. An unknown path such as /api/v1/no-such-thing answers 404 even without a token. A real path without a token answers 401.

Problem documents

Errors from the services are RFC 7807 problem documents, served as application/problem+json. A validation failure looks like this:

{
  "type": "https://essence.digital/errors/400",
  "title": "Validation Failed",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "correlationId": "4be6c4f4-a89e-4df1-99f9-5582dbffe977",
  "serviceName": "auth-service",
  "instanceId": "global",
  "validationErrors": {
    "DeviceFingerprint": ["Device fingerprint is required"]
  }
}

Branch on status and type, never on title or detail: the human-readable text can change and is localised. validationErrors maps each rejected field to the reasons it was rejected. The full list of problem types is in Error codes.

Next

• 5-minute quick start
• SDKs