Errors

Branch on the status code first, then on the stable code in the body when there is one. Retry only the statuses under Retry strategy.

Check the status code, then the envelope

Three layers can reject a request, and each returns a different body shape:

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

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

Status codes

Code	Meaning	Retry?	What to do
`200`	OK	—	Check `succeeded` on geocode and `total` on search.
`202`	Accepted	—	Poll for the outcome. Sent by Auto Apply create, answers, and cancel, and by `GET /api/companies/by-domain` while it builds a profile.
`400`	Bad Request	No	Fix the request; `detail` says what is wrong. Includes undecodable feed cursors.
`401`	Unauthorized	No	Fix the key: missing, malformed, revoked, or expired `X-Api-Key`.
`402`	Payment Required	After top-up	Included jobs and wallet balance can’t cover the request. Top up your wallet.
`403`	Forbidden	No	Not allowed for this key or account. See 403 Forbidden.
`404`	Not Found	No	Unknown id, or an endpoint a sandbox key can’t call (`not_available_in_sandbox`). A company with no jobs returns `200` and an empty array.
`409`	Conflict	Depends on `code`	Restart the feed cursor or saved-feed scan, or resolve the idempotency-key conflict.
`413`	Payload Too Large	No	Shrink the request body.
`415`	Unsupported Media Type	No	Send `Content-Type: application/json`.
`422`	Unprocessable Content	No	Fix the request: well-formed JSON the endpoint can’t act on.
`429`	Too Many Requests	Yes	Wait at least `Retry-After` seconds. See Rate limits.
`499`	Client Closed Request	—	You disconnected before the response was written.
`500`	Internal Server Error	Yes	Back off exponentially. If it persists, check status.
`503`	Service Unavailable	Yes	Search or feed backend busy, profiling unavailable, or a transient conflict. Honor `Retry-After`.

Your wallet is never charged for a failed request. Per-job endpoints (search, feed, company jobs) charge only for delivered jobs; if that charge can’t be covered, the jobs are withheld and you get 402. Flat-rate endpoints such as geocode refund their up-front debit on any 4xx or 5xx. See Billing.

Gateway errors

These are returned before the request reaches an endpoint, as plain JSON, not problem+json.

401 Unauthorized

The response also sets WWW-Authenticate: ApiKey realm="api.jobo.world". On /api/auto-apply/* paths the body also carries api_version.

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

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

402 Payment Required

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). quota_remaining is the number of included jobs you have left. See Billing. Three other surfaces return the same 402 with a different envelope:

Where	Envelope	Match on
Dashboard Export and Outbound (dashboard APIs, not this host)	JSON with a sentence-form `message`	`error`: `"insufficient_credits"` (lowercase)
`GET /api/companies/by-domain/status`, when delivering a ready profile cannot be covered	`problem+json`	`title`: `"Insufficient credits"`
The MCP server	`problem+json`; `detail` includes a top-up link	`title`: `"Insufficient credits"`

Match on the status and the error or title string, which are stable. The prose in detail and message can change at any time.

403 Forbidden

This key or account may not use the endpoint. A 403 is never a plan check. Keys have no per-endpoint scopes, and Feed works on any plan: without Unlimited, it uses included jobs, then the pay-as-you-go rate. Four situations produce a 403:

Situation	Envelope	Match on
A playground token (`jbe_sbx_…`) used outside job search and the job feed	Gateway JSON	`error`: `"sandbox_token_audience_forbidden"`
`POST /api/jobs/feed/managed` or `POST /api/jobs/feed/{feed_id}` with a master or marketplace key	`problem+json`	`title`: `"Customer API key required"`
`GET /api/companies/by-domain` or `/by-domain/status` before Company Enrichment is activated	`problem+json`	`code`: `company_enrichment_not_enabled`
Auto Apply create without live access, or any mailbox endpoint without Auto Apply enabled	`problem+json`	`code`: see Auto Apply errors

Playground tokens are short-lived tokens from the public jobo.world playground. Their refusal:

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

Two related refusals are 404, not 403: a saved feed id owned by another account, and a sandbox key calling an endpoint the sandbox does not serve (code: not_available_in_sandbox).

429 Too Many Requests

The response also sets Retry-After and the X-RateLimit-* headers. group names the rate-limit group you exhausted, and detail names the window, the group, and the limit.

{
  "code": "rate_limit_exceeded",
  "error": "Rate limit exceeded",
  "detail": "Per-minute JobSearch request limit of 180 exceeded. Try again shortly.",
  "group": "JobSearch",
  "retry_after_seconds": 42
}

The Auto Apply groups add api_version. The 429 for repeated authentication failures has no code.

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 string. Branch on it, not on title or detail, which are prose and may be reworded.

`code`	Status	Meaning
`invalid_request`	`400`	A parameter failed validation.
`invalid_cursor`	`400`	The feed cursor could not be decoded. Restart pagination.
`company_enrichment_not_enabled`	`403`	Company Enrichment is not activated for this account.
`not_available_in_sandbox`	`404`	A sandbox key called an endpoint the sandbox does not serve.
`feed_cursor_restart_required`	`409`	A legacy `stable_scan: false` cursor reached the 1,000,000-result limit.
`feed_changed`	`409`	The saved feed was edited since the scan started. Restart the scan.
`request_conflict`	`409`	Conflicts with current state or a prior idempotent request.
`payload_too_large`	`413`	The 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.

Not every error carries a code. For requests made with a customer API key:

400, 409, 413, 415, 422, and 429 carry one, except the authentication-failure 429.
403 and 404 carry one only for access gates (company_enrichment_not_enabled, auto_apply_not_enabled), the sandbox (not_available_in_sandbox), and other Auto Apply domain errors.
401 and 402 never do.

Without a code, match on the status and the error or title string. For customer API keys, endpoint errors with status 400, 409, 413, 415, or 422 also carry docs_url, a link to the relevant docs page. The gateway 429 has code but no docs_url.

Unhandled errors

An unexpected server failure returns a minimal envelope. Its detail field is filled only outside production, so never depend on it.

{ "message": "An error occurred" }

A transient database conflict returns 503 with the same { "message" } envelope and Retry-After: 2. Retry it.

Auto Apply errors

Auto Apply is coming soon; you can build against it today with a sandbox key, no approval needed. Its errors are 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	Retry?
`400`	`idempotency_key_required`	The `Idempotency-Key` header is missing or longer than 200 characters.	No
`400` / `422`	`invalid_target`	`400`: send exactly one of `job_id` or `apply_url`. `422`: a sandbox key can only target `https://sandbox.jobo.world/apply/…` forms.	No
`403`	`auto_apply_agreement_required`	A live key without current acceptance of the Auto Apply Terms and DPA. Accept them in the dashboard.	No
`403`	`auto_apply_not_enabled`	Live Auto Apply is not enabled for this account. Use a sandbox key, or request live access.	No
`403`	`auto_apply_review_required`	Your business review is not approved yet.	No
`409`	`idempotency_key_reuse`	The key was already used to completion for a different body.	No
`409`	`idempotency_key_in_flight`	A request with this key is still being processed.	Yes, shortly, with the same key
`409`	`concurrency_limit_reached`	Active applications are at your limit (two by default; the body has `limit` and `active`). Cancel or submit one first.	No
`429`	`application_capacity_exceeded`	200 nonterminal applications per account. Let some finish, or cancel them.	Yes, after `Retry-After` (60 seconds)
`429`	`application_quota_exceeded`	10,000 creates per rolling 24 hours.	Yes, after `Retry-After`
`422`	`job_apply_url_missing` / `unsupported_ats` / `ambiguous_ats`	The target could not be resolved to a supported provider.	No
`503`	`provider_catalog_unavailable`	No verified provider catalog is published.	Yes, with backoff

With a live key, create runs the three 403 checks in the order under Access: agreement, enablement, business review. A sandbox key skips all three. The answers endpoint adds 400 validation_failed (per-field errors, nothing consumed), 409 invalid_state, and 409 stale_correction_round. See The application loop. An application that fails after being queued reports a failure.code instead, such as answers_timeout when a step’s answer window expired.

Silent failures

These three cases return a success status, so they look like empty or unfiltered data rather than errors.

An unrecognized filter value returns zero results, not a 400

Enum filters are matched literally against the index. An unknown value matches nothing and returns 200 with total: 0, never 400.

# 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 never match a 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. Send ["full-time", "contract"].Occupation filters behave the same way. Take their values from GET /api/occupations:

job_categories and job_subcategories match the taxonomy name, ignoring case (Healthcare or healthcare, not Health care).
occupation_ids matches the occupation id. An occupation name such as Registered Nurse returns 200 with total: 0.
A subcategory whose name contains a comma (Film, TV & Stage Production) is split by the comma-separated GET parameter and matches nothing. Send it on POST /api/jobs/search.

An unknown parameter is ignored, not rejected

Unrecognized parameters are ignored, so a typo returns plausible but unfiltered results. ?is_remote=true filters nothing, because the remote filter is work_model=remote.Search reports unknown query parameters and body fields as an unknown_request_fields warning, in the body and the X-Jobo-Warnings header:

{
  "warnings": [
    { "code": "unknown_request_fields", "message": "Ignored unrecognised query parameters: is_remote." }
  ]
}

Feed requests ignore unknown fields without a warning. Unknown include_facets names are also dropped silently: ?include_facets=work_models (plural typo) returns no facets, not the default set.

Geocode returns 200 for input it cannot resolve

Placeholder and unresolvable input is not an error. Check succeeded, 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 returns 400. See Resolve locations.

Retry strategy

Retry only 429, 500, and 503, plus Auto Apply’s 409 idempotency_key_in_flight. Every other status means the request must change.

Honor Retry-After

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

Back off exponentially with jitter

On 500, or a 503 without Retry-After, wait 1 second and double the wait each time, up to 30 seconds. Add ±25% jitter so concurrent clients don’t retry in lockstep.

Cap attempts

Stop after 3–5 attempts. A persistent 429 means your sustained rate is too high: slow the pipeline down instead of retrying harder.

Restart a cursor instead of retrying it

A cursor error fails on every retry. On 400 invalid_cursor, restart the scan. On 409 feed_cursor_restart_required, start again with {"stable_scan": true, "batch_size": 1000}. On 409 feed_changed, restart the saved-feed scan. See Pagination.

Give feed requests enough time

Set a response timeout of at least 120 seconds on feed calls. The feed can work for up to 90 seconds before it returns a retryable 503.

Send an idempotency key on writes

A retried write that reuses the key 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
        if attempt == max_attempts - 1:
            break  # out of attempts: don't sleep before giving up

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

    return response

The official 4.0.0 clients retry 429 and 503 for you, but not 500: catch JoboServerError and apply the backoff above. Other errors raise a typed exception that carries the problem code; see Client libraries.

Getting support

Every response carries an x-correlation-id header. Quote it when you contact 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

Conventions

Jobs

Feed

Companies

Locations

Auto Apply

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