Errors

When the API returns an error, the response body carries a code field plus a docs_url that points to the page for that code. The CLI and MCP server both render the code inline so you can jump straight to the fix.

Error response shape

CLI, MCP server, and any client that sends Accept: application/vnd.justcrawl.v1+json receive structured errors:

{
  "error": {
    "code": "invalid_url",
    "message": "The URL is malformed or missing a scheme. Use https:// or http://.",
    "docs_url": "https://docs.justcrawl.io/guides/errors/invalid_url",
    "request_id": "req_01HF3...",
    "param": "url"
  }
}

Browsers and other clients receive { "error": "Something went wrong" } and the same details land in our logs against the request_id. Quote that ID when contacting support.

Authentication (401, 403)

Code	Status	Summary
`auth_missing`	401	No bearer token or API key was supplied.
`auth_invalid`	401	The credentials are wrong, expired, or revoked.
`auth_forbidden`	403	You’re authenticated but lack permission for this action.
`auth_org_mismatch`	403	The resource belongs to a different organization.

Validation (400)

Code	Status	Summary
`invalid_url`	400	URL is malformed or missing the scheme.
`invalid_workflow`	400	Workflow JSON is malformed or fails DAG validation.
`invalid_input`	400	One or more request fields are missing or malformed.
`node_type_unknown`	400	The workflow uses an unrecognized node type.

Resource (404, 409)

Code	Status	Summary
`not_found`	404	The requested resource does not exist.
`workflow_disabled`	409	Workflow is disabled. Re-enable it before submitting jobs.
`org_not_found`	404	The organization does not exist or is not accessible.

Quota and billing (402, 429)

Code	Status	Summary
`quota_exceeded`	429	Rate limit or quota hit. Slow down or raise the cap.
`plan_required`	402	This feature requires a higher plan tier.
`payment_required`	402	Payment required. Update billing to continue.

State conflict (409)

Code	Status	Summary
`conflict`	409	Request conflicts with the current state of the resource.
`already_exists`	409	A resource with that identifier already exists.
`job_terminal`	409	The job is in a terminal state and cannot be modified.

CLI device-flow lifecycle (410)

These only fire from the POST /cli-auth/poll endpoint that jc auth login uses. RFC 8628 says expired or consumed codes return 410 Gone so the CLI stops polling deterministically.

Code	Status	Summary
`auth_code_expired`	410	The authorization code has expired. Start a new `jc auth login`.
`auth_code_consumed`	410	The authorization code was already used. Start a new `jc auth login`.

Server and upstream (500, 502, 503)

Code	Status	Summary
`provider_unavailable`	502	The upstream scraping provider is temporarily unavailable.
`internal_error`	500	An unexpected error occurred. The team has been notified.
`service_unavailable`	503	The service is temporarily unavailable. Try again shortly.

Still stuck?

Contact support with your request_id (looks like req_01HF3JKB...). We’ll find the exact failure in our logs in seconds.