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/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.