Errors and status codes

Every error the Embedded API returns, what caused it, and what to do about it — including the failures that succeed quietly.

This page lists the errors the Embedded API returns, what each one means, and how to recover from it.

The error shape

Every error uses the same body:

{
  "statusCode": 409,
  "message": "User already exists with this email",
  "error": "Conflict"
}

Field
statusCode	HTTP status, repeated in the body.
message	A string, or an array of strings when request validation fails.
error	The HTTP status name, such as Conflict.

There is no stable machine-readable error code yet. Branch on statusCode and, where you must distinguish two errors sharing a status, match on message. Treat message as unstable: log it, show it to your own operators, but do not parse it in a way that a wording change would break.

Validation errors return an array

When a request body fails validation, message is an array with one entry per invalid field:

{
  "statusCode": 400,
  "message": [
    "email must be an email",
    "phoneNumber must be a valid phone number"
  ],
  "error": "Bad Request"
}

Handle both shapes:

const detail = Array.isArray(body.message) ? body.message.join('; ') : body.message

Errors by status

400 — Bad Request

Message	Cause	What to do
BVN must be exactly 11 digits	The Bank Verification Number (BVN) is not 11 digits after trimming.	Strip spaces and check the length before you call. See Sandbox test data.
NIN must be exactly 11 digits	The National Identification Number (NIN) is not 11 digits after trimming.	As above.
An array of field messages	One or more body fields failed validation.	Fix the named fields. The array is exhaustive — you do not need to retry to discover the next fault.

401 — Unauthorized

Message	Cause	What to do
Unauthorized	The x-api-key header is missing, malformed, or revoked.	Check the header is present and that you are using the key for the environment you are calling.
Invalid webhook signature	An inbound webhook failed signature verification.	Verify you are computing the signature over the raw request body, before any JSON parsing.

403 — Forbidden

Message	Cause	What to do
User does not belong to this partner	The bmoniUserId in the path exists but belongs to another partner.	Use a bmoniUserId your own key created. This is the error you get from pasting an identifier out of another environment or another partner’s example.

404 — Not Found

Message	Cause	What to do
User not found	No user matches this bmoniUserId.	Confirm you stored the bmoniUserId from the create-user response, not your own employee identifier.
requested item could not be found	Passed through from upstream. The resource does not exist, or it exists but is not yet in a state this endpoint serves.	See A 404 does not always mean missing. From an identity look-up in the sandbox it means the number is not one of the test personas.
No webhook config found	No webhook is configured for this partner scope.	Create one with POST /v1/webhooks before you expect deliveries.

409 — Conflict

Message	Cause	What to do
User already exists with this email	A user already holds that email. The message names the field that actually collided, and lists several joined by and when more than one did.	Reuse the existing user rather than creating another. This is the correct response to a retry of a create that already succeeded — see Retries and duplicates.
Webhook config already exists for this partner scope. Use PATCH to update.	A webhook already exists for this scope.	Use PATCH instead of POST.

500 — Internal Server Error

A 500 here is usually an upstream error passed through unchanged rather than a fault in the proxy. The two you are most likely to meet both come from signature validation:

Message	Cause	What to do
Point is not on curve	The bytes submitted as signature are not a decodable secp256k1 signature — wrong length, wrong encoding, or r/s/v assembled in the wrong order.	See Why your signature is rejected.
Invalid yParityOrV	The v byte is 0 or 1 instead of 27 or 28.	Normalise with v = yParity + 27. See Why your signature is rejected.
The current status does not allow it	The card is in a state that does not permit the requested transition.	See Card status transitions. Do not retry unchanged — the state will not change on its own.

These are validation faults reported with a 500. Returning 400 for a malformed signature is tracked as platform work; until it lands, treat a 500 carrying one of the messages above as a client-side bug and fix the request rather than retrying it.

Failures that return success

The dangerous errors are the ones that do not look like errors. Each of these returns 2xx.

Employment data is dropped when the occupation does not resolve

You send an occupation as free text. The API matches it to an occupation code, and silently omits your employment data when no match is found. The call returns success. Nothing in the response says the data was dropped.

Matching works as follows:

1. The API searches occupations using your occupation string as the search term.
2. It looks for an active occupation whose display name equals your string exactly, ignoring case and surrounding whitespace, or one of whose aliases does.
3. If there is no exact match but the search returned exactly one active result, that one is used.
4. Otherwise no code is resolved, and employment is not sent upstream.

So a title that returns several near-matches and matches none of them exactly — Financial Administrator is the recorded example — resolves to nothing and is discarded.

Do not send occupation as free text in production. Resolve the code yourself and send occupationCode, which is never silently dropped.

GET /v1/users/{userId}/kyc/occupations?search=financial

Pick the entry you want from the response and submit its code:

PATCH /v1/users/{userId}/kyc
{
  "employment": {
    "employmentStatus": "employed",
    "occupationCode": "15-1252",
    "employerName": "Acme Ltd"
  }
}

Then confirm it stuck, rather than trusting the 2xx:

GET /v1/users/{userId}/kyc

If employment is absent or its occupationCode is null, the write did not land.

Card status transitions

The current status does not allow it means the card is not in a state that permits what you asked for. Retrying the same call cannot succeed — one recorded case retried four times over sixteen hours against an unchanged state.

Through the Embedded API you can set exactly two statuses — BLOCKED to freeze and ACTIVE to unfreeze:

PUT /v1/users/{userId}/cards/{cardId}/status
{
  "status": "BLOCKED"
}

A card also carries issuer-set statuses you can only read, such as pending on a card that has never been activated. Attempting a transition the issuer does not permit from the card’s current state produces this error.

Read the current status before you try a transition:

GET /v1/users/{userId}/cards/{cardId}

The full status list, the reason there is no published transition matrix, and the ACTIVE-does-not-mean-activate trap are covered in Card statuses.

A 404 does not always mean missing

requested item could not be found is an upstream message that covers two different situations, and the distinction matters when you are polling.

The clearest case is the proposal signing payload. GET …/proposals/{proposalId}/sign-payload returns 404 until the proposal reaches PENDING_SIGNATURES. The proposal exists; it is simply not ready to be signed.

So a 404 from sign-payload after you have just approved a proposal means wait and try again, not the proposal is gone. Confirm with GET …/proposals/{proposalId}: if that returns the proposal, keep polling sign-payload.

Retries and duplicates

There are no idempotency keys on the Embedded API today. When a request times out and you did not read a response, you cannot assume it failed.

Create-user is the case that matters most, because a blind retry is what turns one intended user into two. It is protected by a uniqueness check on email, phone number, and employee identifier, so a retry of a create that already succeeded returns 409 naming the field that collided — not a second user.

Treat that 409 as success from a previous attempt, not as a failure:

const res = await createUser(payload)

if (res.status === 409) {
  // The earlier attempt landed. Recover the existing user instead of retrying.
  const existing = await findUserByEmail(payload.email)
  return existing
}

Wallet creation has no equivalent uniqueness guard, so a blind retry there can produce a second wallet. Before you retry a wallet create that timed out, list the account’s wallets and check whether the first attempt landed.

GET /v1/users/{userId}/smart-wallets/account/balances

Retry only when that shows no wallet for the currency you were creating.

Idempotency keys on user and wallet creation are tracked as platform work. When they ship, this section will describe them and the read-before-retry workaround above becomes unnecessary.

Related

• Sign a proposal — the full diagnosis path for a rejected signature.
• Sandbox test data — values that resolve, and values that fail on purpose.
• Transfers — the proposal lifecycle these errors appear in.
• SDK error handling — the equivalent surface in bmoni_embedded_sdk.

---

Last reviewed: 7 August 2026.