Errors
Every error response from the RekberPay API follows the same shape:
{
"success": false,
"error": {
"code": "SIG_MISMATCH",
"message": "Signature verification failed."
}
}Errors raised by the framework (a body over 1 MiB, a rate limit, an unexpected failure) also carry a requestId next to error. Quote it when you contact support. A real rate limit answer:
{
"success": false,
"requestId": "5f0c2a3e-7b1d-4c8e-9a2f-3d6b1e4c7a90",
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Try again in 60s."
}
}Each endpoint in the API reference lists the codes it can return. This page collects the shared ones. The Errors and rate limits guide shows how to handle them.
The HTTP status code tells you the category. The code field gives you something stable to switch on.
HTTP status categories
| Status | Category | Retry? |
|---|---|---|
400 | Validation / bad input | No, fix the input |
401 | Unauthenticated | No, log in / get credentials |
403 | Forbidden | No, fix permissions |
404 | Not found | No |
409 | Conflict (duplicate, wrong state, an Idempotency-Key still in flight, a write that collided) | Maybe, see specific code |
410 | Gone (expired) | No |
413 | Payload too large | No, shrink the body |
422 | A signed link or a business rule was rejected (bad signature, expired link, unknown seller), or an Idempotency-Key reused with another body | No, fix the input |
423 | Sign-in locked after failed attempts | Later |
429 | Rate limited | Yes, back off |
500 | Internal error | Yes, retry with same idempotency key |
502 / 503 | Upstream gateway down | Yes, retry with backoff |
Error codes
Authentication & signing
| Code | Status | Cause | Recovery |
|---|---|---|---|
SIG_MISMATCH | 422 | sig does not match the canonical string | Re-sign with the correct field order, encoding and secret |
SIG_INCOMPLETE | 422 | A signed link is missing amount, ref, expires or v | Add the missing parameter and sign again |
UNSUPPORTED_SIG_VERSION | 422 | v is not 1 | Send v=1 |
INVALID_AMOUNT | 422 | On POST /v1/escrows/from-link, the signed amount is not plain digits from 1000 to 500000000 | Sign a whole rupiah amount with no decimals, separators or leading zero |
AMOUNT_MISMATCH | 422 | The amount in the request body is not the signed amount | Leave amount out of the body, or send exactly the signed value |
HOST_NOT_ALLOWED | 422 | The link host is not rekberpay.com or an enabled partner host | Build the link on an allowed host |
INVALID_EXPIRES | 422 | expires is not a unix timestamp | Send seconds since epoch |
LINK_EXPIRED | 422 | expires is in the past | Generate a fresh link with a future expires |
EXPIRES_TOO_FAR | 422 | expires is more than 30 days away | Use 30 days or less |
INVALID_REF | 422 | ref is longer than 64 characters | Sign a shorter order reference |
LINK_ALREADY_USED | 409 | A single-use link (one with buyer) was already used and its escrow no longer exists | Sign a new link with a new ref |
LINK_USE_LIMITED | 429 | One buyer made 3 escrows from the same catalogue link within 10 minutes | Wait a few minutes, or sign a link with buyer for one order |
SIGNATURE_REQUIRED | 400 | Partner parameters, amount included, present without a sig | Sign the link. Unsigned partner links are rejected |
UNAUTHORIZED | 401 | No session and no API key | Sign in or send Authorization: Bearer <key> |
SESSION_EXPIRED | 401 | The session cookie is no longer valid | Sign in again |
INVALID_TOKEN | 401 | The API key is wrong or was revoked (a personal key by a rotation; a workspace key by an admin, or because its creator left the workspace) | Use the newest key |
WORKSPACE_KEY_ONLY | 401 | A workspace key (rpe_...) was sent outside /v1/enterprise | Use a personal key for consumer routes |
KEY_IP_NOT_ALLOWED | 401 | A workspace key with an IP allowlist was used from an address that is not on it | Call from a listed server, or change the key's allowed IPs in the dashboard |
KEY_IN_BROWSER | 403 | A workspace key was sent from a browser (the request had an Origin or Sec-Fetch-Site header) | Call the API from your server only |
TURNSTILE_FAILED | 403 (400 on sign-in) | The Cloudflare Turnstile check did not pass | Complete the check again and resend |
CSRF_FAILED | 403 | A session write without the matching X-CSRF-Token | Send the csrf_token from sign-in |
INVALID_CREDENTIALS | 401 | Wrong email or password on sign-in | Check the credentials |
ACCOUNT_LOCKED | 423 | Too many failed sign-ins | Wait and try again |
LOGIN_LOCKED | 429 | Too many failed sign-ins from this address | Wait for Retry-After |
Idempotency
| Code | Status | Cause | Recovery |
|---|---|---|---|
IDEMPOTENCY_KEY_INVALID | 400 | Header value isn't a UUID v4 | Use randomUUID() / uuid.uuid4() |
IDEMPOTENCY_KEY_CONFLICT | 422 | Same key, different request body | Generate a fresh key for the new operation |
IDEMPOTENCY_KEY_IN_FLIGHT | 409 | An earlier request with this key is still processing | Wait and retry the same key; do not generate a new one |
IDEMPOTENCY_LOOKUP_FAILED | 500 | The key could not be checked | Retry with the same key |
IDEMPOTENCY_INSERT_FAILED | 500 | Key could not be registered | Retry with the same key |
Validation
| Code | Status | Cause | Recovery |
|---|---|---|---|
INVALID_BODY | 400 | Body failed Zod schema validation | Check required fields and types |
INVALID_AMOUNT | 400 | ?amount= on the fee estimate is outside 1,000 to 500,000,000 IDR, or a Jasa Pembayaran order has no valid total | Use an amount in range. On POST /v1/escrows/from-link a bad signed amount is 422 INVALID_AMOUNT (see above) and a bad body amount is 400 INVALID_BODY |
INVALID_METHOD | 400 | Withdrawal method not recognized | Use a method the withdrawal form offers |
MISSING_METHOD | 400 | No method supplied | Send a method from /v1/gateways/available-methods |
UNSUPPORTED_METHOD | 400 | No enabled gateway serves this method right now | Re-fetch /v1/gateways/available-methods and pick another |
INVALID_USERNAME | 400 | Username doesn't match ^[a-z0-9_.]{3,30}$ | Lowercase alphanumeric + underscore/dot |
WEAK_PASSWORD | 400 | Password fails the policy: 10 to 128 characters, not your email name or username, not a common password | Pick a longer, less common password |
INVALID_QUERY | 400 | A query parameter is out of range or not valid | Check the parameter |
Resource state
| Code | Status | Cause | Recovery |
|---|---|---|---|
NOT_FOUND | 404 | Resource ID doesn't exist | Verify the ID |
SELLER_NOT_FOUND | 422 | seller UUID isn't a real user | Confirm with support |
BUYER_MISMATCH | 422 | Link buyer isn't the authenticated user | Sign the link for the user who will open it |
INVALID_STATE | 409 | The item cannot take this action in its current state (for example paying an escrow that is already under review) | Refresh and check the current status |
INVALID_TRANSITION | 400 | State machine forbids this action for this role | See escrow lifecycle |
PAYMENT_IN_PROGRESS | 409 | Cancel while a payment for the escrow, or for a milestone of an enterprise deal, is still open | Wait until the payment completes or expires |
AWB_IN_USE | 409 | The tracking number is on another live escrow between different parties | Send the tracking number of this shipment |
AWB_PREDATES_PAYMENT | 409 | The courier recorded the tracking number before the escrow was paid | Send the tracking number of this shipment |
CANCEL_REQUEST_EXISTS | 409 | A request to cancel this escrow by agreement is already waiting for an answer | Wait for the answer, or withdraw your own request |
CANCEL_REQUEST_LIMIT | 409 | You already asked twice to cancel this escrow by agreement | Open a dispute if there is still a problem |
NO_CANCEL_REQUEST, CANCEL_REQUEST_EXPIRED | 409 | There is no open cancel request to answer or withdraw, or it lapsed after 48 hours | Read the escrow's cancel_request |
OWN_REQUEST | 403 | You tried to accept or decline your own cancel request | Wait for the other party, or withdraw it |
Account verification and limits
| Code | Status | Cause | Recovery |
|---|---|---|---|
EMAIL_NOT_VERIFIED | 403 | The account signed up with email and password and has not confirmed its email. Creating, joining or paying escrows, Jasa Pembayaran orders, withdrawals, creating an enterprise workspace, accepting an invite and every workspace route called with a session or personal key wait for it | The user opens the link in the verification email |
EMAIL_DOMAIN_NOT_ALLOWED | 400 | Creating an enterprise workspace from an account on a disposable or reserved email domain | Sign in with an active personal or work email |
KYC_REQUIRED | 403 | A withdrawal for an account whose KYC is not verified. Nothing is debited. A withdrawal already pending is not affected | The user completes KYC and withdraws once it is approved |
NIK_IN_USE | 409 | KYC submit: the NIK already verifies another RekberPay account (an account deleted after its KYC was verified keeps holding it) | The user signs in to the account that holds the NIK, or contacts support |
NAME_MISMATCH | 422 | A withdrawal to a bank account whose holder is not the name on the account's KYC. Nothing is debited | Withdraw to an account in the user's own name, or ask support for a review |
CRYPTO_ADDRESS_NOT_ACTIVE | 403 | A crypto withdrawal to an address that is not in the user's address book, not confirmed from the email, still in its 24 hour wait, or not an exact match (letter case included) | Add and confirm the address, then wait 24 hours |
CRYPTO_DAILY_LIMIT | 400 | Crypto withdrawals would pass the 24 hour cap (Rp10.000.000 by default). Nothing is debited | A smaller amount, later, or a bank withdrawal |
NONKYC_LIMIT_AMOUNT | 400 | Account without KYC: the amount is above the per-escrow limit | Lower the amount or complete KYC |
NONKYC_LIMIT_DAILY | 429 | Account without KYC: too many escrows in the last 24 hours | Try again later or complete KYC |
NONKYC_LIMIT_LIFETIME | 403 | Account without KYC: the lifetime total would be passed | Cancel unpaid escrows that will not go ahead, or complete KYC |
NONKYC_LIMIT_COUNTERPARTY | 403 | Signed link: the seller cannot take this escrow because of their own limits | The buyer contacts the seller |
NONKYC_LIMIT_SELLER_AT_PAYMENT | 403 | Paying a signed-link escrow whose seller has no room left | The buyer contacts the seller |
These refusals also carry a limits object. See Limits for accounts without KYC.
Uploads
| Code | Status | Cause | Recovery |
|---|---|---|---|
FILE_TOO_LARGE | 413 | Over the size limit of the upload type | Send a smaller file |
TYPE_NOT_ALLOWED, TYPE_MISMATCH, POLYGLOT | 400 | Not an allowed image or PDF, content that does not match its type or extension, or a file hiding another format | Send a real JPEG, PNG, WebP or PDF |
IMAGE_TOO_LARGE, IMAGE_DECODE_FAILED | 400 | Too many pixels, or a damaged image | Send a smaller or a fresh image |
PDF_PASSWORD_PROTECTED | 400 | The PDF is locked with a password | Print it to a new PDF, or upload a photo of the page |
PDF_DAMAGED, PDF_TOO_MANY_PAGES, PDF_UNSUPPORTED_ENCODING, PDF_ACTIVE_CONTENT, PDF_EMBEDDED_FILE | 400 | The PDF cannot be opened, is too long, or could not be cleaned | Save it again as a PDF with only the pages you need |
PDF_TOO_HEAVY | 400 | The PDF's pages or images unpack to far more data than a normal document | Save or compress it again, then upload it |
PDF_CHECK_UNAVAILABLE | 503 | The PDF checker is not available right now. The file itself is fine | Try again in a few minutes, or upload a photo of the page |
QUOTA_EXCEEDED | 429 | The daily upload quota is used up | Try again tomorrow |
UPLOAD_INVALID_REF, UPLOAD_NOT_FOUND, UPLOAD_NOT_OWNED, UPLOAD_WRONG_PURPOSE | 400 | An attached URL is not your own upload of the right type | Upload the file again yourself |
UPLOAD_ALREADY_BOUND, UPLOAD_QUOTA | 409 | The upload is already attached elsewhere, or the item has all the attachments it may have | Upload a new copy, or attach fewer files |
The full list is on Uploads.
Authorization
| Code | Status | Cause | Recovery |
|---|---|---|---|
FORBIDDEN | 403 | Authenticated but not allowed | Check role / ownership |
NOT_A_PARTY | 403 | Trying to read/post in an escrow you're not a party to | Buyer or seller only |
NOT_BUYER | 403 | A buyer-only action was called by someone else | Call it as the buyer |
SUSPENDED | 403 | User account is suspended | Contact support |
ACCOUNT_INACTIVE | 403 | The account is closed or being deleted | Contact support |
KEY_NOT_ALLOWED | 403 | An API key called a dashboard-only enterprise route | Use a dashboard session |
SESSION_REQUIRED | 403 | A dashboard action (changing a key's allowed IPs) was called with anything but a dashboard session | Do it in the dashboard |
SCOPE_REQUIRED | 403 | A read-only workspace key tried to write | Use a key with the write scope |
Rate limiting & body size
| Code | Status | Cause | Recovery |
|---|---|---|---|
RATE_LIMITED | 429 | Too many requests in 1 minute | Honor Retry-After, back off |
FST_ERR_CTP_BODY_TOO_LARGE | 413 | Request body over 1 MiB | Trim the body. Attachments use /v1/upload |
Enterprise API
| Code | Status | Cause | Recovery |
|---|---|---|---|
NO_WORKSPACE | 403 | No active workspace, or not a member of the one in X-Enterprise-Account | Check the workspace ID with GET /v1/enterprise/me |
INVALID_ACCOUNT | 400 | X-Enterprise-Account is not a UUID | Send the workspace ID |
INVALID_MODE | 400 | X-Enterprise-Mode (or ?mode= on a GET) is not sandbox or live | Send sandbox or live, or leave it out |
LIVE_LOCKED | 403 | Live was asked for while the workspace's Live is locked, or a Live key was used while Live is locked | Work in Sandbox until RekberPay approves your business verification |
KEY_MODE_MISMATCH | 403 | A workspace key sent X-Enterprise-Mode naming the other mode. The key decides the mode | Remove the header, or use a key of the mode you want (rpe_test_ or rpe_live_) |
CONCURRENT_MODIFICATION | 409 | Someone changed the item first, or two writes hit the same deal or counterparty at once and this one was not applied. Nothing was changed | Read it again and retry. Safe with the same Idempotency-Key: only 2xx answers are stored |
NOT_DRAFT | 409 | Only drafts can be edited or activated | Check the deal status |
NOT_AWAITING_APPROVAL | 409 | The milestone is not waiting for a decision | Read the milestone |
ALREADY_DECIDED | 409 | You already decided in this round | Ask another approver |
SUBMITTER_CANNOT_APPROVE | 409 | The person who delivered the milestone cannot decide on it | Ask another approver |
NOT_APPROVED | 409 | Only an approved milestone can be released | Wait for the approvals |
SPLITS_MISMATCH | 400 | Release splits do not add up to the milestone payout (the amount minus the counterparty's fee share) | Use proposed.payout_amount from GET /v1/enterprise/approvals/:milestoneId |
INSTRUCTION_NOT_ELIGIBLE | 400 | A payout instruction cannot receive this release | Use a verified instruction of the deal counterparty |
COUNTERPARTY_KYB_REQUIRED | 409 | A live release to a counterparty that has not passed business verification. Nothing is queued and the money stays held. Carries counterparty_id, kyb_status and verify_path | Send the counterparty a verification link, and release once RekberPay approves it |
PAYOUT_INSTRUCTION_TAMPERED | 409 | A payout instruction failed its integrity check | Contact RekberPay |
BANK_NAME_MISMATCH | 422 | A payout instruction's account_holder is not the verified name of the company it pays (the counterparty, or your workspace for a workspace-wide one). At release it must be the deal's counterparty, whichever instruction you pick. Nothing is saved or released | Use the company's verified legal name. PT, CV, Tbk, case and punctuation are ignored. For a trading name or an abbreviation, contact RekberPay |
LIVE_FUNDING_IS_PLATFORM_CONFIRMED | 409 | Funding by API only works in Sandbox | Wait for RekberPay to confirm the money |
LAST_OWNER | 409 | The workspace needs at least one active owner | Add another owner first |
IN_USE | 409 | The payout instruction has payouts | Leave it, or add a new one |
LOCKED | 409 | Evidence of an approved or released milestone cannot be deleted | |
KEY_LIMIT | 409 | The workspace already has 10 active API keys in this mode (the cap is per mode) | Revoke one of that mode first |
SCOPE_NOT_ALLOWED | 400 | Creating a key with a Platform scope your Platform terms do not allow, or while Platform is off in that mode | Leave the scope out; GET /v1/enterprise/platform-status lists allowed_scopes |
KEY_REVOKED | 409 | Changing the allowed IPs of a revoked key | Create a new key |
INVALID_ALLOWED_IPS | 400 | Changing a key's allowed IPs: an entry is not an IPv4 or IPv6 address or CIDR range, is a domain name or a /0 range, or the list has more than 20 entries. A live Platform key also needs at least one. On key creation the same problems answer INVALID_BODY | Fix the list; error.details.fieldErrors.allowed_ips says which entry |
IP_ALLOWLIST_REQUIRED | 403 | A live Platform key called /v1/enterprise/platform without an IP allowlist approved by RekberPay | Add your server IPs to the key and wait for approval |
WORKSPACE_LIMIT | 409 | Creating a workspace when you already own the most one account may own (3) | Contact RekberPay |
TRY_AGAIN | 409 | Another workspace sign-up for your account was still running | Try again |
TEMPLATE_LIMIT | 409 | The workspace already has 50 templates | Delete one first |
WEBHOOK_LIMIT | 409 | The workspace already has 10 webhooks in this mode (the cap is per mode) | Delete one of that mode first |
WEBHOOK_PAUSED | 409 | The webhook is paused | Resume it first |
DELIVERY_PENDING | 409 | Send again while a delivery of the same event is still being retried | Wait for it to finish, then send it again if it failed |
WEBHOOK_URL_* | 400 | The webhook URL is not allowed | Use a public https URL |
SIGNING_NOT_CONFIGURED | 503 | Payout or webhook signing is not available right now | Contact RekberPay |
TEST_DEAL | 409 | A sandbox deal cannot release real payouts, and a Sandbox request or deal cannot take a live payment (pay, claim-payment) | Create the deal in Live, or use the sandbox fund call |
LIVE_DEAL_IN_SANDBOX | 409 | A live deal cannot be funded with sandbox money or released from Sandbox, and a live milestone funded with sandbox money never releases real payouts | Switch to Live. If Live is still locked, verify your business first |
FEE_NOT_AGREED | 409 | The counterparty's workspace has not agreed the fee split, or the link ended and the draft waits for a new one. Raised by activate, and by funding as a safeguard | Wait for its answer, or accept its counter-offer (fee_agreement on the deal says whose turn it is) |
NOTHING_TO_ACCEPT | 409 | No split from the other workspace is waiting for you | Read fee_agreement.proposed_by |
ALREADY_AGREED | 409 | The split is already agreed, so it cannot be countered | Ask the payer to change the draft |
NO_FEE | 409 | The deal was made before platform fees and has no split to counter | Nothing to do |
INVALID_FEE_ALLOCATION | 400 | split without fee_buyer_percent, or buyer or seller with a percent that disagrees | Use buyer, seller, or split with a percent from 0 to 100 |
COUNTERPARTY_REQUIRED | 409 | Activating a deal that has no counterparty | Set counterparty_id first |
COUNTERPARTY_NOT_FOUND | 404 | The counterparty is not in this workspace | Check the ID |
COUNTERPARTY_UNLINKED | 409 | The counterparty was unlinked from its workspace and takes no new deal until it is linked again | Send a new link request and wait for its acceptance, or use it as a regular counterparty |
NOT_ON_HOLD | 409 | use-as-regular on a counterparty that is not waiting for a new link | It already takes new deals |
DUPLICATE_COUNTERPARTY | 409 | Adding a counterparty whose company name matches one you already have. existing lists the matches | Use the existing one, or send allow_duplicate: true |
RESEND_TOO_SOON | 429 | An invite was already sent in the last 10 minutes. For a deal preview link or a link invitation: the last email went out less than an hour ago | Wait for Retry-After seconds, then resend |
EMAIL_NOT_SENT | 502 | An invite resend could not be sent | Resend again in a minute |
WORKSPACE_NOT_FOUND | 404 | No workspace has the Workspace ID in a link request | Ask the other company to copy its ID from GET /v1/enterprise/me or Settings |
SAME_WORKSPACE | 400 | A link request names your own workspace | Use the other workspace's ID |
ALREADY_LINKED | 409 | The counterparty is already linked to a workspace | Unlink it first |
NOT_LINKED | 409 | The counterparty has no link and no open request, or the link is no longer accepted | Read the link with GET /v1/enterprise/counterparty-links |
COUNTERPARTY_LIVE_LOCKED | 409 | A live deal (create, update or activate) names a counterparty linked to a workspace whose Live is still locked. | Create the deal in Sandbox, or ask the partner to verify its business |
LINK_HAS_LIVE_DEALS | 409 | From Sandbox: ending a link that serves Live, or using a counterparty as a regular one, while the paying workspace has live deals with that partner | Switch to Live and do it there |
COUNTERPARTY_HAS_LIVE_DEALS | 409 | From Sandbox: changing the name or country of a counterparty that has live deals | Switch to Live and change it there |
COUNTERPARTY_LIVE_VERIFIED | 409 | From Sandbox while Live is unlocked: changing the name or country of a counterparty that is verified or has a payout override, which Live relies on (it may have no live deals yet) | Switch to Live and change it there |
LIVE_SETTING_SANDBOX | 409 | From Sandbox while Live is unlocked, or while Live is locked again with live deals on file: changing a setting or the default fee split that also applies to Live | Switch to Live and change it there (after a relock: once Live opens again) |
DEAL_ARCHIVED | 409 | A shared deal is completed or cancelled and is a read-only record | Nothing to do |
SANDBOX_WORKSPACE | 409 | A Sandbox request tried to answer a split, deliver on or dispute a live shared deal | Switch to Live. If Live is still locked, verify your business first |
NO_MANUAL_PAYMENT | 409 | claim-payment on a milestone whose newest payment is not a pending manual transfer | Start one with pay, using a manual method |
TOO_MANY_PAYMENT_LINKS | 429 | A milestone already has 5 open attempts on automatic gateways | Use one of them or wait for it to expire |
INVALID_CHANNEL | 400 | Paying a milestone or a whole deal (pay): channel is not a bank or store the chosen method offers, or a store payment (cstore) has no channel. Consumer payments answer the same | Pick a channel from the methods list, or leave it out where none is needed |
AMOUNT_OUT_OF_RANGE | 400 | pay: the total, fee included, is outside what the chosen method accepts. The message gives the range | Choose another method |
GATEWAY_MISCONFIGURED | 503 | pay: the chosen method is not available right now. Nothing was charged or reserved | Choose another method, or retry later |
PAYEE_DELIVERS | 409 | Delivering a milestone (submit-evidence) on a deal shared with the counterparty's workspace. The counterparty delivers it from its own side | Ask the counterparty to deliver from its shared deal |
DEAL_CREATE_BUSY | 409 | Another deal of the workspace is being created at the same moment | Retry |
NOT_CANCELLABLE | 409 | Nothing on the deal is left to cancel: every milestone is released, disputed or already cancelled (a disputed milestone stays with its dispute). Also answered when no money is held but a milestone is released next to unfunded ones, with the message "A milestone is already funded. Open a dispute instead." | Wait for the dispute to be decided |
NO_MILESTONES | 409 | Activating a deal with no milestone | Add one first |
INVALID_DOCUMENTS | 400 | A document of the evidence or dispute is not in this workspace, deal or milestone. From Sandbox while Live is unlocked or has live deals, also a document on no deal (it is shared with Live) | Register the document first; from Sandbox, upload it to the deal |
NOT_DISPUTED | 409 | dispute-evidence on a milestone whose dispute is not open | Add evidence while the dispute is open |
APPLICATION_LOCKED | 409 | KYB: the application is submitted and waiting for review, so it cannot change | Wait for the decision |
ALREADY_VERIFIED | 409 | KYB: the workspace or counterparty is already verified | Nothing to do |
INCOMPLETE | 422 | KYB: submitting while a step is not complete. error.details lists what is missing | Finish the missing steps and documents |
SUSPENDED | 409 | KYB: a suspended business tried to submit | Contact RekberPay |
DOCUMENT_LIMIT | 409 | KYB: the application already has 40 documents | Remove one first |
PERSON_NOT_FOUND | 404 | KYB: person_id is not on this application | Use a person id from application.people |
INVITE_INVALID | 404 | A KYB verification link is malformed, revoked or replaced | Ask for a new link |
INVITE_EXPIRED | 410 | A KYB verification link is older than 14 days | Ask for a new link |
INVITE_CLAIMED | 403 | Another RekberPay account already opened this KYB verification link | Ask for a new link |
INVITE_OTHER_EMAIL | 403 | A KYB verification link was emailed to another address | Sign in with that verified address, or ask for a new link |
SAME_FILE | 409 | KYB: the file is the one the reviewer asked you to replace (on attach, or on submit with doc_type) | Upload a corrected or newer copy |
NOTHING_CHANGED | 422 | KYB: submitting a rejected application again with nothing changed | Change what the reviewer asked for, then submit |
KYB_UNAVAILABLE | 503 | Business verification is not available right now | Retry later |
KYB_SEAL_ERROR | 500 | A protected KYB value could not be read | Contact RekberPay |
PAYMENT_IN_PROGRESS | 409 | A live payment can still land on the deal, so it cannot be cancelled yet, and a cancellation cannot be proposed | Wait until RekberPay confirms the payment or it expires |
FUND_WHOLE_DEAL | 409 | The deal is funded upfront and is not funded yet, so a milestone cannot be paid or funded alone | POST /v1/enterprise/deals/:id/pay (or /fund in Sandbox) for the whole deal |
NOT_UPFRONT | 409 | A whole-deal payment call on a deal that is paid per milestone | Pay or fund each milestone |
FUNDING_MODE_LOCKED | 409 | funding_mode was changed on a deal that is no longer a draft | Set the mode before activation |
CANCEL_ALREADY_PROPOSED | 409 | A cancellation proposal is already waiting for the counterparty to answer | Wait, or withdraw it with DELETE /v1/enterprise/deals/:id/cancel-request |
CANCEL_NOT_PROPOSED | 409 | There is no open cancellation proposal (none was made, it was withdrawn, answered or ran out its 7 days) | Read the deal's cancel_request |
KYB_REQUIRED | 403 | The counterparty workspace acted on a live deal before its business verification was approved. Reads and test deals are never refused | Verify the business, then retry |
PAYEE_CHOSE_PAYOUT | 409 | Release with splits on a deal where the counterparty chose its payout account | Release with no splits |
PAYER_ONLY | 403 | The counterparty side tried to add or remove a required document | Ask the paying workspace |
REQUIREMENT_MISMATCH | 400 | An upload does not match the document requirement it names | Upload a shared file of the required type, on the same milestone when the requirement names one |
REQUIREMENT_MET | 409 | Removing a document requirement that already has its document | Leave it |
FILE_NOT_OWNED | 400 | A room or milestone file is a link, was not uploaded by your workspace, or is already filed somewhere else | Upload it from your workspace first |
FILED_BY_COUNTERPARTY | 403 | Deleting a room file the other workspace filed | Only that workspace can delete it |
EVIDENCE_LOCKED | 409 | Deleting a file on a milestone whose delivery is under review, in dispute or approved | Leave it |
LEAD_NOT_ELIGIBLE | 400 | The deal lead is not an active member of your workspace who can work on deals | Pick another member |
PREVIEW_NOT_ALLOWED | 409 | A preview link action the deal does not allow: a test deal never emails an outside address, Live is not unlocked, the deal is cancelled, the counterparty has a workspace, or there is no contact email | Copy the link instead, or add a contact email |
PREVIEW_OFF | 409 | The preview link is turned off. A reset only works after you turned it off yourself; a cancelled deal, a workspace link or a turn off by RekberPay cannot be reset | Reset it if you turned it off, otherwise nothing to do |
DEAL_NOT_ACTIVE | 409 | A draft deal tried to send or copy a preview link, or to be funded or paid | Activate the deal first |
RESEND_LIMIT_REACHED | 429 | A preview link was already emailed 5 times for the deal, or a counterparty was already invited 5 times | Copy the link instead |
MAIL_LIMIT_REACHED | 429 | RekberPay already sent this contact as many emails as it allows in a day | Wait for Retry-After seconds |
MAIL_FAILED | 502 | The preview link email could not be sent | Copy the link instead |
INVITES_PAUSED | 503 | Invitations by email are paused right now. The send is given back | Try again later |
NO_CONTACT | 409 | The counterparty has no contact email | Add one first |
LINK_EXPIRED | 410 | A preview link expired, was reset or turned off, or a claim link was already used (answered to the person who opened it in the browser) | Ask the sender for a new link |
CLAIM_SELF | 403 | The person who claims a deal from the preview is a member of the workspace that sent it | Use another account |
EMAIL_NOT_VERIFIED | 403 | Claiming a deal with an email that is not verified | Verify the email first |
Platform mode
The partner API under /v1/enterprise/platform has its own codes, such as USER_NOT_AVAILABLE, REF_IN_USE, NAME_LOCKED, NAME_MISMATCH, DAILY_CAP_REACHED, BANK_ACCOUNT_COOLING_OFF, and for chat, tracking and uploads MESSAGE_INVALID, MESSAGE_RATE_LIMITED, ATTACHMENT_INVALID, ATTACHMENT_NOT_FOUND, DEAL_CLOSED_FOR_CHAT, TRACKING_NOT_FOUND and TRACKING_UNAVAILABLE, on the buyer page WEB_SESSION_REQUIRED and NOT_BUYER, on the secure deal link BALANCE_PAYMENT_DISABLED and ORDER_CHANGED, at ship AWB_IN_USE and AWB_PREDATES_PAYMENT, and for account deletion DELETION_BLOCKED, DELETION_NOT_CANCELLABLE and DELETION_NOT_REQUESTED. Every one is listed in the Platform error codes.
Server-side
| Code | Status | Cause | Recovery |
|---|---|---|---|
INTERNAL_ERROR | 500 | Unhandled server error | Retry with same idempotency key |
GATEWAY_ERROR | 502 | The payment gateway rejected or failed the charge request | Retry; if it persists, pick another method |
UNIQUE_CODE_BUSY | 503 | pay with manual bank transfer found no free unique code for that total. Nothing was charged | Retry in a moment, or pick another method |
VALIDATION_FAILED | 400 | Request failed schema validation at the framework layer | Check body and params against the endpoint |
Jasa Pembayaran
| Code | Status | Cause | Recovery |
|---|---|---|---|
FEATURE_DISABLED | 503 | Jasa Pembayaran is switched off | Retry later; check GET /v1/jasabayar/config |
AMOUNT_TOO_LARGE | 400 | item_price above max_item_price_idr | Lower the amount or split the order |
ALREADY_PAID | 409 | Cancel on an order that is no longer awaiting_payment | Contact support if it is funded |
DECRYPT_FAILED | 500 | The order's saved details could not be read | Contact support with the order ID |
DB_ERROR | 500 | Order was not created; no funds were taken | Safe to retry |
Reading error responses
Every error response is JSON. Treat anything else as a network/proxy issue, not a RekberPay error.
const res = await fetch(url, options);
if (!res.ok) {
const ct = res.headers.get('content-type') ?? '';
if (!ct.includes('application/json')) {
throw new Error(`Network error: ${res.status} ${res.statusText}`);
}
const { error } = await res.json();
throw new ApiError(error.code, error.message, res.status);
}Recovery patterns
Idempotent retry on 5xx / network failure
async function withRetry(fn, max = 5) {
let attempt = 0;
while (attempt < max) {
try {
return await fn();
} catch (err) {
if (err.status && err.status < 500) throw err; // 4xx, don't retry
if (attempt === max - 1) throw err;
await sleep(1000 * Math.pow(2, attempt++));
}
}
}Backoff on 429
The response includes a Retry-After header (seconds):
if (res.status === 429) {
const wait = Number(res.headers.get('Retry-After') ?? 60);
await sleep(wait * 1000);
return retry();
}Refresh on INVALID_STATE
if (err.code === 'INVALID_STATE') {
// Fetch the latest state and decide what to do
const { data } = await fetch(`/v1/escrows/${id}/payment-status`).then(r => r.json());
if (data.status === 'paid') {
// Already paid, treat as success
return;
}
throw err;
}Reporting bugs
If you hit a 500 you can't explain, email [email protected] with:
escrow_id(or other resource ID)- Approximate timestamp (UTC)
- Request body (redact secrets)
- Response body
Include the requestId when the error has one.
See also
- Errors and rate limits: handling errors in code
- Idempotency and retries: make retries safe
- Escrows API: errors for each endpoint