Reference

Errors

Every API error — from every service — uses one canonical envelope. Branch on the stable type and code, not on the human-readable message.

The error envelope

{
  "error": {
    "type": "not_found_error",
    "code": "alias_not_found",
    "message": "No identity is registered for this alias.",
    "param": "alias",
    "request_id": "req_7k2...",
    "doc_url": "https://docs.settla.network/errors/alias_not_found"
  }
}

Field	Type	Description
`type`optional	`string`	Broad category, aligned to the HTTP status (see below).
`code`optional	`string`	Specific, stable machine code. Branch on this in your integration.
`message`optional	`string`	Human-readable explanation. Do not parse it.
`param`optional	`string`	The offending field, when the error is about one input.
`request_id`optional	`string`	`req_…` — also returned as the `Settla-Request-Id` response header. Quote it in support requests.
`doc_url`optional	`string`	A link to documentation for the specific code.

Note

Every response — success or error — carries a Settla-Request-Id: req_<22 base62> header that matches request_id in the body. Log it.

HTTP status → type

Status	type	Meaning
400	invalid_request_error	Malformed or missing parameters.
401	authentication_error	Missing, malformed, or revoked credentials.
403	permission_error	Authenticated, but the key lacks the required scope.
404	not_found_error	Resource not found — or hidden by privacy/consent (uniform).
409	conflict_error	Duplicate, or an idempotency-key body mismatch.
422	unprocessable_error	Valid request, but no result is possible (e.g. no compatible route).
429	rate_limit_error	Velocity or breadth quota exceeded; see Retry-After.
5xx	api_error	An unexpected server error. Safe to retry idempotent calls.

Common error codes

code	Status	When it happens
invalid_request	400	Body fails validation (missing alias, bad type, unparseable identifier).
authentication_error	401	No bearer token, or the key is unknown/revoked.
invalid_credentials	401	Human login: wrong email or password.
mfa_required	401	Human login: MFA is enabled and not yet satisfied.
permission_error	403	The key is valid but lacks the required scope.
alias_not_found	404	No resolvable identity for the alias (also returned for private / no-consent).
recipient_not_found	404	recommend-route: resolution disclosed no endpoints.
email_taken	409	Signup: the email is already registered.
idempotency_conflict	409	Same Idempotency-Key reused with a different body.
no_compatible_route	422	recommend-route: no disclosed capability matches the request.
rate_limited	429	Per-key velocity bucket drained.
scraping_quota_exceeded	429	Resolver distinct-alias breadth quota exceeded for the day.

Uniform not-found

For privacy, “does not exist” and “exists but you may not see it” return the same 404 alias_not_found in both shape and timing. Do not infer existence from a 404.