Errors

One envelope, stable codes, and what each one means you should do.

Every refusal has the same shape. The HTTP status says what kind of problem it is; the errorCode is stable and is what you should branch on.

JSON

{
  "errorCode": "SCOPE_NOT_GRANTED",
  "message": "This credential is not scoped for that operation.",
  "details": null
}

Status	Code	What to do
401	INVALID_API_KEY	Check the header. Absent, unknown, revoked and expired all answer this.
403	SCOPE_NOT_GRANTED	Call GET /me. You need a broader scope, or your plan changed.
403	TENANT_SUSPENDED	The institution's account is not being served. Talk to them.
404	SESSION_NOT_FOUND	Wrong identifier, or it belongs to another institution.
404	CASE_NOT_FOUND	Wrong reference, or it belongs to another institution.
409	WORK_FLOW_NOT_PUBLISHED	The journey is not live. Re-read GET /workflows.
409	SANDBOX_SESSIONS_UNSUPPORTED	Use a production credential for hosted sessions.
409	DECISION_NOT_READY	Keep polling the session until it reads DECIDED.
409	PLAN_LIMIT_REACHED	The monthly allowance is spent. The institution can raise it.
409	SERVICES_STOPPED	The institution's account cannot fund the call.
422	UPSTREAM_REJECTED	A provider refused your input. Check it before retrying.
429	RATE_LIMITED	Wait for Retry-After seconds, then retry.
502	UPSTREAM_FAILED	A provider failed. Retry with backoff.
503	TENANT_HOST_NOT_CONFIGURED	A deployment setting is missing. Report it.
504	UPSTREAM_TIMEOUT	A provider did not answer. Retry with backoff.