Errors and limits
{ error: { code, message } }, with x-request-id on every answer. Match on code; the message is for people and may change.HTTP/1.1 409 Conflict
x-request-id: req_4f1c9a0b2e7d3c6a51
4s-livemode: false
{
"error": {
"code": "duplicate_reference",
"message": "You already have a job with reference CLAIM-881 (SJ-1001)"
}
}400invalid_request
A field is missing or out of range. The message names the field.
Fix the field the message names and send it again with a new Idempotency-Key.
400invalid_json
The body isn't JSON.
Send a JSON body with content-type: application/json.
400idempotency_key_required
A write came without an Idempotency-Key header.
Send Idempotency-Key with a unique string of 8 to 100 letters, digits, - or _. Send the same one when you retry.
403forbidden
The key doesn't carry the scope the route needs.
Use a settlement key. It carries settlement:read, settlement:write and webhooks:manage.
403live_only
A test key called a route that works on live data only.
Every settlement route takes a test key. Check the path against the reference.
403no_settlement_tenant
The key isn't linked to a settlement account.
Make the key in your settlement dashboard, or ask your 4 Seasons contact for one.
403live_not_enabled
A live key on an account 4 Seasons hasn't turned live on for yet.
Use a test key until your 4 Seasons contact turns live on for your account.
403draws_off
Draws for lenders aren't switched on.
Ask your 4 Seasons contact. Jobs without a loan work as before.
403tenant_paused
Your settlement account is paused.
Ask your 4 Seasons contact. Nothing is lost while it's paused.
404not_found
The job, step, executor, release or waiver doesn't exist, or belongs to another account or mode.
Check the id. A test key sees only test work, and a live key only live work.
409duplicate_reference
You already have a job with this reference.
Read the job you have with GET /settlement/jobs/{reference}, or use a new reference.
409duplicate
That id is already one of your executors.
Use the executor you have.
409invalid_state
The step or job can't do that now, such as proof for a verified step or moving a paid step to someone else.
Read the job to see where it stands.
409no_executor
Proof came for a step with no executor.
Attach an executor with POST /settlement/jobs/{id}/executors, then send the proof.
409rail_off
The pay rail asked for isn't switched on.
Onboard the executor on Stripe (rail: "stripe").
409request_in_progress
A request with this Idempotency-Key is still running.
Wait a moment and retry with the same key. You get the first answer.
403capacity_off
Live reservations aren't switched on yet.
Use a test key to build against simulated supply. Your 4 Seasons contact can say when live reservations open.
409capacity_taken
The hours asked for aren't all committed and free in that window, or another reservation took them first.
Read GET /settlement/capacity again and reserve what it shows, or widen the window.
409capacity_short
A bulk request that takes all of it or none can't hold every week's hours, so nothing was reserved.
The message gives each short week's hours. Send allowPartial true to hold what is there, with waitlist true to wait for the rest.
409reservation_lapsed
The reservation passed its lapse time before a job was attached.
Reserve the hours again.
422invalid_work_spec
The Work Spec has a duplicate step key, or a step pays more than one step may.
Give each step its own key, and keep each step at or under maxStepPayoutCents from GET /settlement.
422invalid_draw_schedule
The draw schedule doesn't add up: a milestone is missing or in two draws, a draw doesn't equal its milestones, or the draws don't equal the construction budget.
The message names each problem. Amounts must match to the cent.
422payee_not_supported
The loan asks for a payee the pay rail can't pay, such as joint with the borrower.
Use payee.mode "contractor". A joint payment has to be made outside this API.
422idempotency_key_reused
This Idempotency-Key was used with a different body.
Use a new key for a new request. Reuse a key only to retry the same request.
429rate_limited
Too many requests for this key this minute.
Wait retry-after seconds. x-ratelimit-remaining says how many are left.
500server_error
Something failed on our side.
Retry with the same Idempotency-Key. Nothing runs twice.
idempotent-replayed: true. Nothing runs twice.422 idempotency_key_reused. A key still running answers 409 request_in_progress.X-4S-Simulate header are part of the request, so one key can't replay an answer onto a different job or step.Per key per minute, the same for test and live. Every answer carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset. Over the limit you get 429 rate_limited with retry-after in seconds.
limit is 1 to 100. Each page says hasMore and gives a nextCursor.startingAfter=<nextCursor> for the next page. Pages never skip or repeat a row, however many are added while you read.let cursor: string | null = null;
do {
const q = new URLSearchParams({ limit: "100", ...(cursor ? { startingAfter: cursor } : {}) });
const page = await fetch(`https://www.build4seasons.com/api/v1/settlement/jobs?${q}`, {
headers: { authorization: `Bearer ${process.env.FOURS_KEY}` },
}).then((r) => r.json());
for (const job of page.data) console.log(job.number, job.status);
cursor = page.hasMore ? page.nextCursor : null;
} while (cursor);