Error reference

Reading a Connect error code

Two conventions coexist in error bodies, and you need to know that before writing a switch:

Form	Example	Where
Dotted lowercase	`connect.application_fee_too_low`	Business refusals from the Connect cascade
`E_` prefixed	`E_CONNECT_PRICING_UNAVAILABLE`	Infrastructure refusals and shared guards

Always branch on the literal value of the code field in the response body.

Some refusals carry no code at all: target refusals only carry {"message": "Forbidden"} or {"message": "Unauthorized"}. That is deliberate: they must reveal nothing about other people’s accounts.

Target refusals (401 / 403)

Four causes, only two responses.

Internal cause	Status	Body
Malformed identifier	`403`	`{"message": "Forbidden"}`
Unknown or deleted vendor	`403`	`{"message": "Forbidden"}`
Vendor of another marketplace	`403`	`{"message": "Forbidden"}`
Test key targeting a `live` vendor (or the reverse)	`401`	`{"message": "Unauthorized"}`

The first three are byte-identical: the API will never tell you whether an acct_ exists. Otherwise it would become a way to enumerate other marketplaces’ accounts.

Validation refusals (400 / 422)

Code	Status	Cause	Remediation
`connect.incomplete_request`	422	`on_behalf_of` without `application_fee_rate`, or the reverse	Supply both
`connect.fee_payer_unset`	422	Connect is not activated on your account	Activate Connect
`connect.application_fee_too_low`	400	Your commission does not exceed Yabetoo’s fees	See Pricing
`connect.application_fee_too_high`	400	Your commission exceeds the gross amount	Correct the rate
`connect.vendor_net_not_positive`	422	The vendor would receive zero or less	Increase the amount, or lower the commission
`connect.country_unsupported`	422	No operator configured for your country	Contact support
`connect.reversal_exceeds_remaining`	422	The reversal exceeds the allocation’s remainder	Read `remaining` in the body
`E_CONNECT_VENDOR_EMPTY_BALANCE`	422	Available balance is empty	Nominal state, do not retry
`E_CONNECT_VENDOR_PAYOUT_METHOD_UNAVAILABLE`	422	No payout destination	Send the onboarding link again
`E_PENDING_WITHDRAW`	422	A withdrawal is already in flight on this wallet	Wait for its outcome
`E_CURRENCY_MISMATCH`	422	Wallets in different currencies	Not supported in v1
n/a (`rule: "unsupported"`)	422	Rejected field: `phone`, `type`, `fee_payer`, `amount`, `destination`, `account_id`	Remove the field
n/a (`rule: "derived"`)	422	Rejected field: `country`, `kycLevel` on an onboarding link	Remove the field
n/a (`field: "Idempotency-Key"`)	422	Header missing or too long (255 max)	Add the header
n/a (relayed)	422	`connect.controller_mode_unset`: Connect not activated	Activate Connect

Insufficient funds (402)

Code	Route	Who pays as a last resort
`connect.insufficient_funds_for_refund`	Refund	You: the refusal only happens if your balance is not enough either
`connect.insufficient_funds_for_reversal`	Allocation reversal	Nobody: only the vendor is drawn on

Both bodies carry required, seller_available, shortfall, currency. The refund refusal also carries available and marketplace_balance.

402 and not 422: the request is well formed, it is the funds that are missing.

Idempotence conflicts (409)

Code	Cause	What to do
`E_IDEMPOTENCY_CONFLICT`	A request with the same key is in progress	Wait, then retry with the same key
`E_DUPLICATE_OPERATION`	The key has already produced an operation	Do not retry: the operation took place

On POST /v1/connect/accounts/{acct}/withdrawals, a replay returns the original 201 for 24 hours, then 409 E_DUPLICATE_OPERATION. The withdrawal did take place in both cases.

Rate limiting (429)

E_TOO_MANY_REQUESTS on POST /v1/connect/accounts: 20 requests per minute. No other Connect route is rate limited.

Unavailability (502 / 503)

Code	Status	Cause	Retry?
`E_CONNECT_PRICING_UNAVAILABLE`	503	The commission grid could not be resolved	Yes. If the refusal persists, a pricing row is missing: contact support.
`E_CONNECT_AVAILABILITY_DELAY_UNSET`	503	The availability delay is not configured	Contact support
`E_SSO_UNAVAILABLE`	503	The identity service is unavailable	Yes
`E_SERVICE_UNAVAILABLE`	503	An upstream service is unavailable	Yes
`E_IDENTITY_UNAVAILABLE`	503	The verification service is unavailable (compliance read)	Yes
`E_CONNECT_ONBOARDING_UNSUPPORTED`	502	No compliance schedule for this country	No: contact support
`E_REFERENTIAL_COUNTRY_MISSING`	502	Country not found in the reference data	No: contact support

Connect fails closed on pricing. A 503 E_CONNECT_PRICING_UNAVAILABLE means the operation was refused rather than charged at zero. That is deliberate: a silently zero commission would be an invisible loss.

Surface (400)

Body	Cause
`The Yabetoo-Account header is not supported on this endpoint`	You sent the `Yabetoo-Account` header. Connect routes name the vendor in the path or the body.
`The Yabetoo-Account header is only supported with a partner secret key`	Header sent with a credential that is not an `sk_` key

The Yabetoo-Account header is reserved and is consumed by no Connect route today. Do not send it.

Get started

Connected accounts

Accept payments

Pay out

Resources

Reading a Connect error code

Target refusals (401 / 403)

Validation refusals (400 / 422)

Insufficient funds (402)

Idempotence conflicts (409)

Rate limiting (429)

Unavailability (502 / 503)

Surface (400)

​Reading a Connect error code

​Target refusals (401 / 403)

​Validation refusals (400 / 422)

​Insufficient funds (402)

​Idempotence conflicts (409)

​Rate limiting (429)

​Unavailability (502 / 503)

​Surface (400)

Reading a Connect error code

Target refusals (401 / 403)

Validation refusals (400 / 422)

Insufficient funds (402)

Idempotence conflicts (409)

Rate limiting (429)

Unavailability (502 / 503)

Surface (400)