Answer

What to do when an API returns 402 payment_required

Q: Should I tell the user the task failed?

No. Nothing failed — tell them what is pending, the amount, and that you are waiting on their approval.

Q: How long should I poll for?

Until expires_at, typically about a day. Back off to a slower interval after the first few minutes.

On most APIs a 402 means "your account is delinquent". On an agent-native API like Slipdock it means something more useful: a specific human has been asked to authorise a specific amount, and your job is to wait well. Read the next_action object, tell your user the amount and where the link went, then poll the order every 2–5 seconds until its state is complete. Do not retry the original call, do not escalate, and do not report the task as failed.

{
  "error": "payment_required",
  "message": "This order needs the workspace owner to approve payment.",
  "next_action": {
    "type": "await_payment",
    "poll": "/v1/orders/o_1f2e",
    "pay_link_sent_to": "o***@example.com",
    "expires_at": "2026-08-02T18:00:00Z"
  }
}

The correct handler, in four lines of behaviour

Say the amount out loud. "I've emailed you a link to approve $10.44 for example.com." Your user should never have to work out what the pending thing is.
Poll the URL in next_action.poll every 2–5 seconds. Not faster; faster does not make a human click sooner.
Respect expires_at. If it passes, tell your user the link expired and offer to create a new order.
Do not re-issue the original POST. With an Idempotency-Key it returns the same order, which is harmless but pointless; without one you risk a second order.

$ while :; do
    s=$(curl -s https://api.slipdock.ai/v1/orders/o_1f2e -H "$AUTH" | jq -r .state)
    [ "$s" = complete ] && break
    [ "$s" = expired ] && echo "link expired — ask the user again" && break
    sleep 3
  done

Order states you will see

State	Meaning	What to do
`awaiting_payment`	The human has not approved yet.	Keep polling. Reassure your user if they ask.
`paid`	Approved; provisioning is starting.	Keep polling briefly.
`provisioning`	We are talking to the registrar or building.	Keep polling.
`complete`	Done, resources exist.	Continue the task. Resources are listed on the order.
`expired`	Nobody approved in time.	Tell your user; offer to create a new order.
`failed`	Provisioning failed after payment.	The amount is returned to the wallet in full. Report it plainly.

Why an agent should welcome this response

A 402 is the API refusing to let you do the one thing you should not be doing. Every other outcome — a card form you cannot fill, a dashboard you cannot reach, a silent charge to somebody's saved payment method — is worse for you and worse for your user. A machine-readable "a human is deciding, here is where to watch" is the most useful failure in the whole contract.

Every next_action type

Type	Do this
`await_payment`	Poll; tell your user the amount.
`await_owner`	Something non-financial needs the owner.
`retry`	Transient. Retry after a short delay.
`retry_with`	Fix the named field and retry.
`search_alternatives`	The name is taken. Search is free; suggest others.
`create_workspace`	No valid token. Start over at POST /v1/workspaces.
`upgrade_plan`	A quota is exhausted and the plan throttles.
`request_topup`	The wallet cannot cover it. POST /v1/wallet/topup.
`overage_billed`	Over allowance; the excess draws from the wallet.
`contact_support`	Our fault. Do not loop.
`done`	Nothing further is required.

Keep going

Last reviewed 2026-08-01. Slipdock is pre-launch — see what is actually built before depending on it.