sorina.sh
sign in

Errors

Every failure takes one shape: an HTTP status, a stable code to branch on, and a sentence written for whoever is reading the log. Branch on the code. The sentence may be reworded; the code will not be.

{"error":"this request costs $0.0040 and the account balance will not cover it",
 "code":"insufficient_funds"}

Every code

400 bad_request
The body or its arguments did not validate.
no
400 offset_unsupported
The all-results search does not paginate; use a narrower one.
no
400 search_id_required
Page two and later must carry the first page’s search id.
no
401 unauthenticated
Missing, malformed, or unknown key. One answer for all three, on purpose.
no
402 insufficient_funds
The balance will not cover this request.
no
403 key_revoked
The key was withdrawn, or the account is suspended.
no
403 not_on_plan
The plan carries no price for that class, so it refuses it.
no
429 rate_limited
Over the plan’s requests per second. Retry-After: 1.
yes
429 daily_limit_reached
The day’s allowance is spent. Retry-After counts down to 00:00 UTC.
yes
502 upstream_error
The platform failed us. Not charged.
yes
502 upstream_too_large
The platform sent more than we will pass through. Not charged.
no
503 no_session
We cannot reach the platform for you right now. Not charged.
yes
503 session_expired
The same, discovered mid-request. Not charged.
yes
503 auth_unavailable
We could not check your key. Not charged.
yes
503 metering_unavailable
We could not bill the request, so we did not serve it.
yes
504 upstream_timeout
The platform ran past our deadline. Not charged.
yes

What to retry, and how

429 — wait the header out

Both carry Retry-After: one second for going too fast, and the seconds remaining until 00:00 UTC for a spent daily allowance. Honour it rather than backing off blindly — for a daily ceiling, backing off is not going to be enough.

5xx — ours, and free

no_session, session_expired, upstream_error and upstream_timeout mean we could not reach the platform for you. None of them is charged. Retry with a backoff; if a whole class of call keeps failing, it is us and not you.

4xx — fix it first

A 400, 401, 402 or 403 will answer the same way every time you send it. Retrying is only a way to spend your daily allowance on the same mistake.

Three that read alike and are not

401 unauthenticated is every key problem there is — missing, malformed, unknown id, wrong secret. One answer for all four, on purpose: probing the endpoint should not tell you whether an id exists.

403 key_revoked means stop retrying and reissue. 403 not_on_plan means your plan carries no price for that class of request, so it is refused rather than served free.

503 no_session and 503 session_expired are the same condition found at two different moments — we cannot reach the platform for you right now. Neither is charged, and neither means your request was wrong.

And a 200 that is not one

The platform reports some of its own failures inside an HTTP 200. A body with a non-zero status_code is one of those, and it is a successful call as far as we are concerned — we asked, and they answered. Check the body’s own status fields as well as ours.

Only a 2xx is billed. Every code on this page is recorded in your usage at $0.00 — see billing and limits for what does cost, and what still counts against the day.