Accounts errors - Endl API

Every accounts error returns the same five-key envelope, so you only need one parser. Branch on errors[0].code, not on the message text — the codes are frozen and will never be renumbered or reused, while messages may be reworded.

{
  "code": 409,
  "message": "Account is deactivated. Reactivate it before using it",
  "status": "ERROR",
  "data": null,
  "errors": [
    {
      "code": "ERRACC_1002",
      "message": "Account is deactivated. Reactivate it before using it",
      "field": "accountId"
    }
  ]
}

Errors are wrapped; successes are not. A successful accounts response is the bare object — there is no data key to unwrap. Only the error path uses this envelope. See Errors and the response envelope.

When the failure is about one specific input, errors[0].field names it, so you can bind the message straight to a form field. When it is not about an input — authentication, rate limits, a provider outage — it is null rather than filled with prose.

What to do about each status

You get	It means	Do this
`400`	Something in your request is wrong	Fix it and resend. Never retry unchanged.
`401`	Key missing, wrong, or its partner is inactive	Check the `API-KEY` header. Do not retry.
`403`	Valid key, but not allowed	Check the key has `accounts`, and that the customer is yours.
`404`	The customer or account does not exist	Do not retry. Re-check the reference id.
`409`	Conflicts with current state	Read the code: already open, deactivated, or an unsupported provider.
`429`	Too many requests	Back off. The window is one minute.
`502` / `503`	A provider is unavailable	Safe to retry with backoff — nothing changed.
`500`	Unexpected server error	Report it with the `X-Request-ID` response header.

Every code

HTTP	Code	`field`	Message	When	Endpoints
`400`	`ERRACC_1000`	`userId`	User id is required	The `{userId}` path segment is blank or whitespace.	All
`400`	`ERRCORE_1001`	`currency / accountName / displayName`	Validation Failed	A request-body constraint failed. One `errors[]` entry per failed field.	Open account
`400`	`ERRACC_1009`	`accountCategory`	Unsupported account category. Expected one of: FIAT, CRYPTO, ONRAMP	`accountCategory` is not `FIAT` or `ONRAMP`.	Open account
`400`	`ERRACC_1005`	`status`	Unsupported status ’…’. Expected one of: ACTIVE, PENDING, DEACTIVATED, CLOSED, FROZEN, UNDER_REVIEW, DORMANT	An unknown value was passed in `?status=`.	List accounts
`400`	`ERRREF_1000`	`accountId`	’…’ is not a valid account id	`{accountId}` is blank, malformed, or not an `acct_…` reference.	Get, Balance, Activity, Activate, Deactivate
`400`	`ERRREF_1000`	`walletId`	’…’ is not a valid wallet id	`walletId` is missing, blank, or not a `wlt_…` reference.	Open account
`400`	`ERRCORE_1001`	`Api-Version`	The ‘Api-Version’ header is required · Invalid ‘Api-Version’ format · Unsupported ‘Api-Version’: …	The version header is missing, malformed, or names a version the server does not support.	All
`400`	`ERRCORE_1001`	`null`	The request path is not a valid URL	The raw path contains a doubled slash, an encoded slash, a backslash or a control character.	All
`401`	`ERRCORE_1004`	`null`	Partner API key required · Invalid API key · Associated partner is not active or not found	The `Api-Key` header is missing, does not match an active credential, or its partner is inactive.	All
`403`	`ERRCORE_1005`	`null`	Insufficient permissions	The key is valid but lacks the `accounts` permission.	All
`403`	`ERRCORE_1005`	`null`	Access denied — User does not belong to this partner	The customer exists but belongs to a different partner.	All
`403`	`ERRCORE_1005`	`null`	Source IP not allowed for this API key (observed: …)	The calling IP is outside the allow-list configured on the key.	All
`404`	`ERRREF_1001`	`walletId`	Wallet ‘wlt_…’ not found	A well-formed wallet reference that resolves to no wallet for this customer.	Open account
`404`	`ERRREF_1001`	`userId`	User with ID ‘cus_…’ not found	`{userId}` resolves to nothing, or the customer is soft-deleted.	All
`404`	`ERRREF_1001`	`accountId`	Account ‘acct_…’ not found	A well-formed account reference that resolves to no row.	Get, Balance, Activity, Activate, Deactivate
`404`	`ERRACC_1001`	`accountId`	Account not found	The account reference resolved, but no such account belongs to this customer.	Balance, Activate, Deactivate
`404`	`ERRCORE_1002`	`null`	User not found	Relayed from the core service when the resolved user is missing there — a data race, rarely seen.	All
`405`	`ERRCORE_1001`	`null`	HTTP … is not supported for this endpoint	Wrong verb on a real path, e.g. `PUT` on Get Account. Note the code: a 405 carries the validation code `ERRCORE_1001`, not a method-specific one. Key off the HTTP status here.	All
`409`	`ERRACC_1002`	`accountId`	Account is deactivated. Reactivate it before using it	Get Account was called on a deactivated account. Use List to see it, or Activate to bring it back.	Get account
`409`	`ERRACC_1003`	`null`	Balance is not available for this account’s provider	The account sits with a provider that has no balance integration.	Get balance
`409`	`ERRACC_1003`	`null`	Activation is not supported for this account’s provider	The account is AED, or sits with a provider that has no lifecycle integration. AED accounts cannot be activated or deactivated.	Activate, Deactivate
`409`	`ERRACC_1006`	`null`	An account already exists for this currency	The customer already has an active or pending account in that currency.	Open account
`409`	`ERRACC_1018`	`currency`	Account limit reached for this currency	The customer already holds 10 accounts in that currency, counting active and pending accounts combined.	Open account
`415`	`ERRCORE_1001`	`null`	Content type … is not supported; use application/json	A non-JSON `Content-Type` on Open Account. Same quirk as 405 — the code is `ERRCORE_1001`.	Open account
`429`	`ERRCORE_1006`	`null`	Rate limit exceeded, please retry later	The per-API-key limit was exhausted. Carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Safe to retry.	All
`500`	`ERRCORE_1000`	`null`	An error occurred while processing your request	An unexpected server error. Quote the `X-Request-ID` when reporting it.	All
`502`	`ERRACC_1011`	`null`	The balance could not be retrieved. Please try again in a moment	The provider answered but returned no balance. Safe to retry.	Get balance
`502`	`ERRACC_1004`	`null`	The status change could not be accepted. Please try again in a moment	The change could not be queued. Nothing was applied, so it is safe to retry.	Activate, Deactivate
`503`	`ERRACC_1012`	`null`	The account provider is temporarily unavailable. Please try again later	The provider threw or timed out. Safe to retry.	Get balance

Two codes cover “you cannot open another account in this currency”. ERRACC_1018 is the ceiling — 10 per currency, active and pending combined. ERRACC_1006 reports that an account already exists for the currency. Match on errors[0].code and handle both, rather than assuming only one of them can reach you.

A 405 and a 415 both carry ERRCORE_1001 — the validation code — rather than a method- or media-specific one. Key off the HTTP status for those two.

A malformed id is a 400, not a 404. ERRREF_1000 means the reference did not parse as an acct_… or wlt_… id at all. ERRREF_1001 means it parsed correctly but resolves to nothing. Different fixes, so they are different codes.

Worked examples

400 · validation

One entry per failed constraint. The envelope message is always the literal Validation Failed, and field names the real property.

400

{
  "code": 400,
  "message": "Validation Failed",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRCORE_1001", "message": "Currency is mandatory!", "field": "currency" },
    { "code": "ERRCORE_1001", "message": "Account Name is mandatory!", "field": "accountName" },
    { "code": "ERRCORE_1001", "message": "Display name must not exceed 50 characters", "field": "displayName" }
  ]
}

400 · business rule

A domain error carries its own ERRACC_* code and names the offending parameter.

400

{
  "code": 400,
  "message": "Unsupported account category. Expected one of: FIAT, CRYPTO, ONRAMP",
  "status": "ERROR",
  "data": null,
  "errors": [
    {
      "code": "ERRACC_1009",
      "message": "Unsupported account category. Expected one of: FIAT, CRYPTO, ONRAMP",
      "field": "accountCategory"
    }
  ]
}

400 · bad reference

A malformed id is a 400, not a 404. A well-formed id that resolves to nothing is the 404.

400

{
  "code": 400,
  "message": "'zxsdf' is not a valid account id",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRREF_1000", "message": "'zxsdf' is not a valid account id", "field": "accountId" }
  ]
}

401 · auth

Raised before routing. field is always null on a 401.

401

{
  "code": 401,
  "message": "Partner API key required",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRCORE_1004", "message": "Partner API key required", "field": null }
  ]
}

403 · permission

Either the key lacks the accounts permission, or the customer belongs to another partner. field is always null.

403

{
  "code": 403,
  "message": "Insufficient permissions",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRCORE_1005", "message": "Forbidden", "field": null }
  ]
}

404 · not found

Customer and account both report through this shape, distinguished by field.

404

{
  "code": 404,
  "message": "User with ID 'cus_missing' not found",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRREF_1001", "message": "User with ID 'cus_missing' not found", "field": "userId" }
  ]
}

409 · conflict

Three distinct causes: a duplicate account on open, a deactivated account on get, and an operation the provider does not support.

409

{
  "code": 409,
  "message": "Account is deactivated. Reactivate it before using it",
  "status": "ERROR",
  "data": null,
  "errors": [
    {
      "code": "ERRACC_1002",
      "message": "Account is deactivated. Reactivate it before using it",
      "field": "accountId"
    }
  ]
}

429 · rate limit

Read X-RateLimit-Limit and X-RateLimit-Remaining from the response headers. The window is one minute and rejection is immediate — back off rather than retrying tightly.

429

{
  "code": 429,
  "message": "Rate limit exceeded, please retry later",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRCORE_1006", "message": "Rate limit exceeded, please retry later", "field": null }
  ]
}

500 · server error

Quote the X-Request-ID response header when you report one.

500

{
  "code": 500,
  "message": "An error occurred while processing your request",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRCORE_1000", "message": "Unknown Error", "field": null }
  ]
}

502 / 503 · retryable

Both are safe to retry with backoff — no state was changed.

502 / 503

{
  "code": 503,
  "message": "The account provider is temporarily unavailable. Please try again later",
  "status": "ERROR",
  "data": null,
  "errors": [
    {
      "code": "ERRACC_1012",
      "message": "The account provider is temporarily unavailable. Please try again later",
      "field": null
    }
  ]
}

Retrying safely

Codes	Retry?
`ERRACC_1011` — the balance could not be retrieved	Yes, after a moment. The provider answered but returned no balance.
`ERRACC_1012` — the provider is temporarily unavailable	Yes, with backoff.
`ERRACC_1004` — the status change could not be accepted	Yes. Nothing was applied.
`ERRCORE_1006` — the rate limit	Yes, after the window. One minute.
`ERRCORE_1000` — an unexpected server error	Once, then report it with the `X-Request-ID`.
Everything else `4xx`	No. Fix the request or the credential.

The full cross-service catalogue, including the other ERR modules, is on Error codes.

​What to do about each status

​Every code

​Worked examples

​400 · validation

​400 · business rule

​400 · bad reference

​401 · auth

​403 · permission

​404 · not found

​409 · conflict

​429 · rate limit

​500 · server error

​502 / 503 · retryable

​Retrying safely

What to do about each status

Every code

Worked examples

400 · validation

400 · business rule

400 · bad reference

401 · auth

403 · permission

404 · not found

409 · conflict

429 · rate limit

500 · server error

502 / 503 · retryable

Retrying safely