Errors

Check the status code, then the envelope

The API returns three different error shapes depending on which layer rejected the request. Write your error handling against the status code first, and only then read the body.

Layer	Content type	Shape	Statuses
Gateway — auth, rate limits, wallet	`application/json`	`{ "error", "detail", … }`	`401` `402` `403` `429`
Endpoint — validation, conflicts	`application/problem+json`	RFC 7807 `ProblemDetails` + `code`	`400` `404` `409` `413` `415` `422`
Unhandled — unexpected failure	`application/json`	`{ "message" }`	`500`

A 200 is not always a success. GET /api/locations/geocode returns 200 with succeeded: false for input it cannot resolve, and a search filter with an unrecognised value returns 200 with total: 0 rather than an error. See silent failures.

Status codes

Code	Meaning	Retry?	What to do
`200`	OK	—	Check `succeeded` on geocode; check `total` on search.
`202`	Accepted	—	Auto Apply create and cancel. Poll for the outcome.
`400`	Bad Request	❌ Fix request	Read `detail`. Includes undecodable cursors.
`401`	Unauthorized	❌ Fix key	Missing, malformed, revoked, or expired `X-Api-Key`.
`402`	Payment Required	❌ Top up	Wallet balance too low. Top up your wallet, then retry.
`403`	Forbidden	❌	Managed feed without a customer key, or a sandbox-token audience mismatch.
`404`	Not Found	❌	Unknown id. Note a company with no jobs returns `200` and an empty array.
`409`	Conflict	⚠️ Conditional	Feed cursor must be restarted, or an idempotency-key conflict.
`413`	Payload Too Large	❌ Fix request	Shrink the request body.
`415`	Unsupported Media Type	❌ Fix request	Send `Content-Type: application/json`.
`422`	Unprocessable Content	❌ Fix request	Well-formed JSON the endpoint cannot act on.
`429`	Too Many Requests	✅	Wait `Retry-After` seconds. See Rate limits.
`499`	Client Closed Request	—	You disconnected before the response was written.
`500`	Internal Server Error	✅	Exponential backoff. If persistent, check status.
`503`	Service Unavailable	⚠️ Conditional	Feed backend busy — honour `Retry-After`. Auto Apply create is gated off.

Credits are never charged for a failed request. Per-delivered-unit endpoints (search, feed, company jobs) run a balance precheck and only debit after a successful response is built. Flat-rate endpoints such as geocode debit up front and are automatically refunded on any 4xx or 5xx. See Billing.

Gateway errors

These come from middleware, before your request reaches an endpoint. They are plain JSON, not problem+json.

401 Unauthorized

Also sets WWW-Authenticate: ApiKey realm="api.jobo.world".

{ "error": "Missing X-Api-Key header" }

{ "error": "Invalid or expired API key" }

402 Payment Required

One condition produces this status on the API: your remaining included jobs plus your wallet balance cannot cover the request. The response also sets X-Credits-Required and X-Credits-Balance:

{
  "error": "Insufficient credits",
  "detail": "This request needs 75 credits ($0.075). Your wallet balance is 12 credits ($0.012). Top up your wallet to continue.",
  "group": "JobSearch",
  "credits_required": 75,
  "credits_balance": 12,
  "quota_remaining": 10,
  "cost_per_request_usd": 0.075
}

Credits are the wallet’s wire unit — 1,000 credits = $1.00 — and quota_remaining is your included jobs remaining; see Billing. The same condition surfaces in two other places with the same status but a different envelope. Dashboard Export and Outbound (portal APIs, not this host) return 402 with the error value "insufficient_credits" (lowercase) and a sentence-form message. The MCP server relays a problem+json document whose title is "Insufficient credits" and whose detail includes a top-up link. In every case, match on the status and the error / title string — those values are stable — and treat the prose detail / message as rewordable at any time.

403 Forbidden

Only two situations produce a 403:

POST /api/jobs/feed/managed called with anything other than a customer API key — master, marketplace, and sandbox keys are rejected.
A sandbox token used against a product it was not minted for.

{
  "api_version": "2026-08-12",
  "error": "sandbox_token_audience_forbidden",
  "detail": "This sandbox token is not valid for the requested product endpoint."
}

API keys have no per-endpoint product scopes. Search and Feed can run from included jobs or at the pay-as-you-go rate; the Unlimited plan is a billing option , not a requirement to call Feed.

429 Too Many Requests

Also sets Retry-After and the X-RateLimit-* headers. group names the rate-limit group you exhausted — Default, JobSearch, JobFeed, Geocode, AutoApply, or AutoApplyManagement.

{
  "code": "rate_limit_exceeded",
  "error": "Rate limit exceeded",
  "detail": "Per-minute request limit reached.",
  "group": "JobSearch",
  "retry_after_seconds": 42
}

Endpoint errors

Validation and conflict errors follow RFC 7807 with Content-Type: application/problem+json.

{
  "title": "Invalid cursor",
  "detail": "The supplied cursor could not be decoded.",
  "status": 400,
  "code": "invalid_cursor",
  "docs_url": "https://jobo.world/docs/guides/sync-a-database"
}

Stable error codes

code is a stable, lowercase, machine-readable string. Branch on it rather than on title or detail, which are prose and may be reworded at any time.

`code`	Status	Meaning
`invalid_request`	`400`	A parameter failed validation.
`invalid_cursor`	`400`	The cursor could not be decoded. Restart pagination.
`feed_cursor_restart_required`	`409`	A legacy non-stable cursor reached the deep-pagination boundary.
`request_conflict`	`409`	Conflicts with current state or a prior idempotent request.
`payload_too_large`	`413`	Request body exceeded the limit.
`unsupported_media_type`	`415`	Send `Content-Type: application/json`.
`unprocessable_request`	`422`	Valid JSON, but not actionable.
`rate_limit_exceeded`	`429`	A rate-limit window is exhausted.

code is present on 400, 409, 413, 415, 422, and 429 only, and only for requests authenticated with a customer API key. 401, 402, 403, and 404 carry no code — match on the status and the error string for those. Auto Apply is the exception: it returns code on its domain errors throughout.

Responses carrying a code also carry docs_url, pointing at the relevant page here.

Unhandled errors

An unexpected server-side failure returns a minimal envelope. A detail field is only populated outside production, so never depend on it.

{ "message": "An error occurred" }

Auto Apply errors

Auto Apply is an invite-only beta. Its errors use problem+json with a stable code, and every Auto Apply response — errors included — carries api_version. POST /api/auto-apply/applications refuses before queueing anything when:

Status	`code`	Meaning
`403`	`auto_apply_not_enabled`	The account has not been invited to the beta. Not transient — do not retry.
`409`	`idempotency_key_reuse`	The key was already used to completion for a different body.
`409`	`idempotency_key_in_flight`	A request with this key is still being processed.
`422`	`job_apply_url_missing` / `unsupported_ats` / `ambiguous_ats`	The target could not be resolved to a supported provider.
`503`	`provider_catalog_unavailable`	No verified provider catalog is published. Transient — retry with backoff.

The answers endpoint adds 400 validation_failed (per-field errors, nothing consumed), 409 invalid_state, and 409 stale_correction_round — see The application loop. Applications that fail after being queued report a failure.code instead, including answers_timeout when a step’s answer window expired.

Silent failures

Three cases return a successful status with no data and no error. They account for most “the API returned nothing” reports.

An unrecognised filter value returns zero results, not a 400

Enum filters are matched literally against the index. There is no validation and no 400 — an unknown value matches nothing, and you get 200 with total: 0.

# Zero results — "senior level" is not a canonical value
curl "https://connect.jobo.world/api/jobs?experience_level=senior+level" \
  -H "X-Api-Key: $JOBO_API_KEY"

# Matches
curl "https://connect.jobo.world/api/jobs?experience_level=senior" \
  -H "X-Api-Key: $JOBO_API_KEY"

Send the canonical values listed under Enums. Jobs where the field is null are excluded from any filter on that field.On POST /api/jobs/search, array values are not comma-split: ["full-time,contract"] is one literal value and matches nothing. Use ["full-time", "contract"].

An unknown query parameter is ignored, not rejected

Unrecognised query parameters are silently dropped, so a typo returns unfiltered results that look plausible. ?is_remote=true is not a parameter — the filter is work_model=remote — so that request succeeds while filtering nothing.The same applies to include_facets: unknown names are dropped, so ?include_facets=work_models (plural typo) yields no facets rather than the default set.

Geocode returns 200 for input it cannot resolve

Placeholder and unresolvable input is not an error. Check the succeeded field, not the status code.

{
  "input": "2 Locations",
  "succeeded": false,
  "error": "Location string is a placeholder, not a real location."
}

Only a missing or whitespace-only location parameter is a real 400. See Resolve locations.

Retry strategy

Retry only 429, 500, and 503. Everything else is a request you must change.

Honour Retry-After

On 429 and 503, wait exactly the number of seconds in the Retry-After header. Never hardcode a delay.

Back off exponentially with jitter

For 500, start at 1s and double, capping around 30s. Add ±25% jitter so concurrent clients do not retry in lockstep.

Cap attempts

Stop after 3–5 tries. Persistent 429 means your sustained rate is too high — slow the pipeline down rather than retrying harder.

Treat a feed 409 as a restart, not a retry

On feed_cursor_restart_required, discard the cursor and begin pagination again with {"stable_scan": true, "batch_size": 1000}. Retrying the same cursor fails forever.

Send an idempotency key on writes

So a retry cannot double-charge or duplicate work. See Idempotency.

import random, time, requests

RETRYABLE = {429, 500, 503}

def request_with_retry(method, url, *, headers, max_attempts=5, **kwargs):
    response = None
    for attempt in range(max_attempts):
        response = requests.request(method, url, headers=headers, **kwargs)
        if response.status_code not in RETRYABLE:
            return response

        # Retry-After is authoritative when present (429, 503).
        retry_after = response.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else min(2**attempt, 30)
        time.sleep(delay * random.uniform(0.75, 1.25))

    return response

The official clients do this for you as of 4.0.0: 429 and 503 are retried with bounded backoff honouring Retry-After, and everything else raises a typed exception — JoboAuthenticationError, JoboPermissionError, JoboNotFoundError, JoboRateLimitError, JoboValidationError, JoboCursorRestartRequiredError, and JoboServerError, all deriving from JoboError and carrying the problem code. See Client libraries.

Getting support

Every response carries an x-correlation-id header. Quote it when contacting support@jobo.world — it identifies the exact request in our logs.

curl -si "https://connect.jobo.world/api/jobs?q=engineer&page_size=1" \
  -H "X-Api-Key: $JOBO_API_KEY" | grep -i x-correlation-id

Overview

API essentials

Jobs

Feed

Companies

Locations

Auto Apply — Preview

Check the status code, then the envelope

Status codes

Gateway errors

401 Unauthorized

402 Payment Required

403 Forbidden

429 Too Many Requests

Endpoint errors

Stable error codes

Unhandled errors

Auto Apply errors

Silent failures

Retry strategy

Getting support

​Check the status code, then the envelope

​Status codes

​Gateway errors

​401 Unauthorized

​402 Payment Required

​403 Forbidden

​429 Too Many Requests

​Endpoint errors

​Stable error codes

​Unhandled errors

​Auto Apply errors

​Silent failures

​Retry strategy

​Getting support

Check the status code, then the envelope

Status codes

Gateway errors

401 Unauthorized

402 Payment Required

403 Forbidden

429 Too Many Requests

Endpoint errors

Stable error codes

Unhandled errors

Auto Apply errors

Silent failures

Retry strategy

Getting support