Guide

Responses & errors

Every Identra response — success or failure — is the same JSON envelope. Parse it once and the whole API reads consistently: check success, then read data or error.

2xx Success

JSON

{
  "success": true,
  "data": { "id": "018f3c4a-7b2e-7c1d-9e0a-1f2b3c4d5e6f", "primary_email": "user@example.com" },
  "error": null,
  "meta": { "timestamp": "2026-01-15T09:30:00Z" }
}

4xx · 5xx Error

JSON

{
  "success": false,
  "data": null,
  "error": { "code": "not_found", "message": "No user matches that id." },
  "meta": { "timestamp": "2026-01-15T09:30:00Z" }
}

Status codes

The HTTP status carries the category; the error.code is the stable, machine-readable handle you branch on. Messages are human-readable and client-safe — they never contain internals or secrets.

Status	error.code	Meaning
200 · 201	—	Success. The payload is in data; error is null.
400	bad_request	Malformed request — unparseable body or bad parameter.
401	unauthorized	Missing, invalid, or expired credential.
403	forbidden	Authenticated, but not allowed (default-deny).
404	not_found	No such resource in this application.
409	conflict	State conflict, e.g. an email already in use.
422	validation	Validation failed; message says which field.
429	rate_limited	Too many requests — back off and retry.
500	internal	Unexpected server error. Never leaks internals.

The envelope, from the contract

This is the ErrorEnvelope type exactly as the API emits it — the success variant swaps a populated data for the null error.

data any
error ErrorBody required
meta Meta required
success boolean required