Errors

The error object, what each status means, and every public error code with what to do about it.

A request that fails answers a non-2xx status and an error object:

JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "amount must be greater than or equal to 10000",
    "param": "amount",
    "doc_url": "https://bezanbecard.com/docs/errors#amount_too_small",
    "request_id": "req_…"
  }
}

Errors
Field	Description
`type`	The family of the error, below.
`code`	A stable, machine-readable reason. Branch on this, not on `message`.
`message`	A sentence for developers, in English. Do not show it to customers.
`param`	The parameter at fault, in bracket form for nested ones (`customer_details[phone]`).
`doc_url`	The entry for `code` on this page.
`request_id`	Also in the `Request-Id` header of every answer. Quote it when you contact support; your request logs in the dashboard are searchable by it.

Types and statuses

Types and statuses
`type`	Status	Meaning
`invalid_request_error`	400, 402, 404, 409, 413	The request is wrong for the current state: a bad parameter, a plan limit, an unknown id, a conflict.
`authentication_error`	401	No key, or a key that does not work.
`permission_error`	403	The key works but may not do this.
`idempotency_error`	400, 409	An `Idempotency-Key` was reused with another body, or is still in use.
`rate_limit_error`	429	Too many requests; wait for `Retry-After`.
`api_error`	5xx	Something failed on our side. Retry with the same `Idempotency-Key`.

The official libraries raise one exception class per type (see libraries).

Request codes

`parameter_missing`

A required parameter is absent. param names it.

`parameter_unknown`

The body has a parameter the endpoint does not take. Check the spelling against the API reference.

`parameter_invalid`

A parameter has a value the endpoint does not accept, or an expand[], created or cursor parameter is malformed.

`parameter_invalid_integer`

A parameter must be a whole number, such as limit (1 to 100) or an amount in rial.

`parameter_invalid_empty`

A parameter was sent as an empty string where a value is required.

`amount_too_small`

The amount is below 10,000 rial.

`amount_too_large`

The amount is above 2,000,000,000 rial.

`json_invalid`

The body is not valid JSON.

`request_too_large`

The body is larger than 100 KB.

`url_invalid`

No endpoint has this path and method.

`not_implemented`

This endpoint or feature is not available yet.

`resource_missing`

No object with this id exists in this account and mode (a test id with a live key is missing too), or a pagination cursor names no object of the list.

`resource_already_exists`

An object with these unique values already exists.

`resource_conflict`

The object was changed by another request at the same moment. Read it again and retry.

`api_version_invalid`

The Bezanbecard-Version header names a version that does not exist.

Authentication and permission codes

`api_key_missing`

No key was sent. Send Authorization: Bearer sk_….

`api_key_invalid`

The key is not one of Bezanbecard's, or was mistyped.

`api_key_revoked`

The key was revoked. Create a new one.

`api_key_expired`

The key was rolled and its overlap time has passed. Use the new key.

`permission_denied`

A restricted key lacks the access this request needs. Edit its permissions or use another key.

`secret_key_required`

A publishable key was sent. Every endpoint needs a secret or restricted key.

`test_mode_only`

The endpoint, such as POST /v1/test_helpers/deposits, works with test keys only.

`account_suspended`

The account is suspended, so its keys are refused. Contact support.

`account_restricted`

The account is restricted (by an operator, or for an unpaid invoice): live payments cannot be created, everything else works. Pay the invoice or contact support.

`billing_limit_reached`

The plan's limit for this resource (live payment links, cards, phones or team members) is reached. Upgrade the plan or archive one.

Idempotency codes

`idempotency_key_invalid`

The Idempotency-Key header is empty or longer than 255 characters.

`idempotency_key_reused`

This key was used with a different request in the last 24 hours. Use a new key for a new operation.

`idempotency_key_in_use`

The first request with this key is still running. Retry in a moment.

`rate_limit`

Too many requests for this key: 100 a second in live mode, 25 in test mode. A receipt upload may also be asked to wait a few seconds while the server is busy reading other uploads. Wait for the Retry-After seconds.

Payment codes

`payment_already_changed`

The payment changed while your request ran (a deposit arrived, a teammate acted), another change to the payment was still running, or (for resolve_overpayment) a customer credit for another figure than the overpayment is still unrecorded and a team member must settle it. In that second case nothing ran, so a retry with the same Idempotency-Key runs; otherwise read the payment again and decide again.

`payment_action_unavailable`

The action does not apply to the payment in its current status, such as approving a payment that already succeeded.

`payment_not_open`

The payment is closed, so it can no longer be updated or topped up.

`payment_amount_unavailable`

No unique amount is free on the card right now (very many open payments asking for nearly the same amount). Retry, or pass another card.

`payment_amount_invalid`

The amount is outside the payment limits.

`payment_expiry_invalid`

expires_in is outside 300 to 86,400 seconds.

`payment_card_invalid`

card is not an active card or account of this account and mode that takes one of your enabled payment methods.

`payment_customer_invalid`

customer is not a customer of this account and mode.

`payment_customer_required`

Resolving an overpayment as credited needs a payment that belongs to a customer.

`payment_deposit_invalid`

deposit is not a deposit of this account and mode.

`payment_deposit_not_attached`

The deposit to detach is not attached to this payment.

`payment_overpayment_not_pending`

The payment has no pending overpayment to resolve.

`payment_metadata_invalid`

metadata breaks a limit: at most 50 keys, keys up to 40 characters, values up to 500, strings only.

`card_none_available`

No active card or account can take this payment: there is none in this mode that takes an enabled payment method, or every one reached its daily limit. Add a card or an account, enable another payment method, or raise a limit.

Deposit codes

`deposit_already_matched`

The deposit is already attached to a payment. Detach it there first.

`deposit_already_changed`

The deposit changed while your request ran. Read it again and retry.

`deposit_given_back`

The money of this deposit was given back to the customer (refunded or credited), so it cannot be attached to the payment again. Create a new payment if the customer pays again.

`deposit_receipt_partial`

An approved receipt of this payment already covers part of this transfer. Correct that receipt instead of attaching the bank deposit, which would count the same transfer twice.

`deposit_not_matched`

The action needs a matched deposit.

`deposit_card_required`

There is no card to put the deposit on: pass card, or add an active test card.

`deposit_card_invalid`

card is not a card of this account and mode.

`deposit_amount_required`

Pass amount, or a payment that still expects a transfer.

`deposit_payment_invalid`

payment is not a payment of this account and mode.

Receipt codes

`receipt_action_unavailable`

The decision does not apply to the receipt in its current status: it was already approved, rejected or replaced. Read it again.

`receipt_already_changed`

The receipt changed while this request ran, so nothing was approved. Retrieve it and decide again on what it shows now. On the dashboard the approval dialog also gets this code when what it showed no longer holds (it said the approval adds no money or reopens nothing, or it named an overpayment, and a teammate's decision, a detach or a cancel changed that meanwhile); the dialog then shows the new figures. A teammate who decided the same receipt first gives you receipt_action_unavailable instead.

`receipt_amount_required`

Nothing says how much to approve: the receipt has no amount and the payment expects none, or you confirm an overpayment (overpay: true) on a receipt with no amount. Send amount.

`receipt_amount_mismatch`

The bank SMS deposit of this transfer has another amount. Approve the bank's amount, or detach that deposit first. Linking a deposit to a receipt that stands on a receipt deposit answers it too when the two amounts differ (param is deposit): a replacement never moves money.

`receipt_deposit_invalid`

deposit names no bank deposit on the payment's card or account.

`receipt_deposit_unavailable`

The deposit is matched to another payment, or another receipt already stands on it or is corroborated by it.

`receipt_deposit_taken`

No longer sent: an older answer for a deposit that already backed another approved receipt. Read it as receipt_deposit_unavailable.

`receipt_payment_settled`

Approving would add more than the payment still asks for, so it records an overpayment (on a payment that already succeeded, all of it). Send overpay: true to confirm the overpayment. param is overpay; /v1 sends no amount with it.

`receipt_payment_refunded`

The payment was canceled or expired and its money was given back to the customer (refunded or credited), so no receipt is approved on it. A new transfer needs a new payment.

`receipt_overpayment_resolved`

The payment's overpayment was already resolved (refunded, credited or kept), and this approval would overpay it beyond that. Approve at most what the payment still asks for, or reject the receipt. param is amount.

`receipt_channel_unavailable`

The payment does not take this kind of transfer, such as paya on a payment that takes card to card only.

`receipt_field_required`

A field the payment needs is missing; param names it, such as channel on a payment that takes bank transfers only.

`receipt_payment_invalid`

The payment filter names no payment of this account and mode.

Receipt file codes

`file_too_many`

A receipt takes at most 3 files.

`file_too_large`

A file is larger than 10 MB. The status is 413.

`file_invalid_type`

A file is not a JPEG, PNG, WebP or HEIC image or a PDF. The type is read from the file's bytes, never from its name.

`file_invalid_upload`

The multipart body could not be read. Send the files in the field files.

Payment link codes

`link_amount_required`

A fixed link needs amount[value].

`link_amount_invalid`

The amount, a bound or a preset is outside the payment limits, or a preset is outside the bounds.

`link_amount_range_invalid`

amount[min] is greater than amount[max].

`link_after_url_required`

after_completion[type] is redirect without an after_completion[url].

`link_limits_invalid`

max_uses must be a positive whole number.

Customer codes

`customer_phone_taken`

Another customer of this mode has this mobile number. Use that customer.

`customer_phone_invalid`

The mobile number is not an Iranian mobile number.

`customer_payments_open`

The customer has open payments; finish or cancel them before deleting.

Webhook endpoint codes

`webhook_url_invalid`

The URL is not valid, or is not https for a live endpoint.

`webhook_destination_private`

The URL resolves to a private or loopback address.

`webhook_events_required`

enabled_events is empty.

Connect codes

`connect_code_invalid`

The connect code is unknown, already used or expired. Start the connection again from the plugin.