jobhunt.app/mcp

Limits and errors

Request rate limits (HTTP 429), size limits and the error codes an integration or agent can receive.

Updated

Step by step

  1. Request rate

    Each API key, and each OAuth connection for one account, may make 100 requests per minute by default. The MCP endpoint separately allows four protocol messages for each of those requests, 400 per minute, because a client may negotiate, initialize and acknowledge around one tool call. Browser sessions are not limited per key. A page image link (/api/v1/page-images/...) carries no credential, so those links are limited separately: 120 fetches per minute from one network address, enough for every page of the largest document and a few retries. Over that the answer is HTTP 429 as plain text with a Retry-After header; fetch the remaining pages after that many seconds, asking for new links if they expired. A page image of a saved document or saved version is drawn when it is fetched, so each account may also have 40 such pages drawn in 10 minutes, from any address; past that the link answers HTTP 429 with Retry-After and new previews are refused with rate_limited until then. Page images of exported or prepared PDFs do not count toward it. Page image links are encrypted and say nothing about the account or the document. The limits on newsletter sign-up, referral-code checks and shared pipeline pages are also counted per connecting network address. An X-Forwarded-For header sent by a client is ignored, so changing it does not reset the count.

  2. When you are over the limit

    The response is HTTP 429 with the code rate_limited and a Retry-After header in seconds. Wait that long, then send the same request again with the same request identifier. A tool result may carry retry_after_seconds instead. If the limiter itself cannot be reached, the response is HTTP 503 with the code rate_limit_unavailable; try again later. Two requests that arrive at the same moment are counted one after the other; that alone no longer causes the 503 answer.

  3. Sign-in and sign-up limits

    Sign-in attempts (10 a minute), new accounts (5 a minute), password-reset requests (10 every 15 minutes), sign-in email links (10 every 15 minutes) and newsletter sign-ups (5 a minute) are counted per network address. When someone uses the jobhunt.app website, the website tells JobHunt that person’s own address, so each person has their own count and other people signing in at the same time do not use it up. A request sent straight to the API host is counted against the address it connects from. An address a client names in a header, including X-Forwarded-For, is not trusted. Starting an assistant connection while signed out is limited too: 30 starts every 15 minutes, counted against the address the request reaches JobHunt from. Past that, the page says to start again in a few minutes; wait, then start a new connection from your assistant.

  4. Size limits

    A request to the MCP endpoint may be at most 524,288 bytes. A resume file to import may be at most 10 MB and 20 PDF pages; pasted or extracted resume text at most 100,000 characters. Export chunks are at most 64,000 bytes before base64 encoding. Other operations state their own bounds in their input schema.

  5. Numbers out of range on two CRM routes

    POST /api/v1/crm/followups/generate takes a limit from 1 to 100 (10 when you leave it out), and POST /api/v1/contacts/{contact_id}/quiet takes days from 1 to 3650 (60 when you leave it out). Anything else, such as 0, a negative number, a larger number, null, a string, a fraction or true or false, is answered HTTP 400 with the code invalid_limit or invalid_days, and nothing is changed. Send a whole number within the range.

  6. Error codes from operations

    A failed operation returns one of: authentication_required (sign in or reconnect); account_changed (the connected account is not the one the request was bound to; stop and check with the person); insufficient_scope (the connection was not granted the permission; HTTP 403); access_unavailable; not_found; invalid_input (fix the arguments; do not retry unchanged); revision_conflict (the record changed; read it again and reapply the change to the current revision); request_id_conflict (the request identifier was already used with a different payload; do not invent a new identifier to get past it); source_unavailable; processing_failed; rate_limited; retry_expired (the window for retrying the original request has closed; read the current state before deciding what to do). From the MCP tools, an invalid_input refusal names the input as the tool names it, in field, and says why in the message.

  7. After a lost reply

    Do not assume failure. Over HTTP, read the original operation with get_job_hunt_operation, using its operation ID or the request ID and operation name. An assistant uses get_operation_status with the request ID and the tool it called. Retry only with the same identifier and payload.

What happens next

An integration that honours Retry-After, keeps its request identifiers and re-reads on revision_conflict does not create duplicates or overwrite newer work.

These numbers are the defaults in the running service on 16 November 2026. The OpenAPI document at https://jobhunt.app/api/v1/openapi.json lists the responses each HTTP operation can return.

Troubleshooting

An HTTP 401 from the MCP endpoint carries a WWW-Authenticate header that names the OAuth protected-resource metadata; start sign-in from there. The codes above are the complete set a tool result can carry; the message beside the code says what happened in plain words and is safe to show the person.

Technical detailsAPI operations and permissions

These operation details and permissions come from the API contract.

READget_connected_account

Identify the JobHunt account connected by these credentials. The opaque account ID stays unchanged across renaming, reconnection and token refresh. This does not select or change a resume contact profile.

GET /api/v1/journey/get_connected_account

DECLARED PERMISSIONS

  • read:profile
View input, output and access requirements →
READget_job_hunt_operation

Read a saved JobHunt operation after a retry or lost response. Use the original operation ID or request ID and operation name; optionally bind the expected payload hash. Full profile-photo receipts expose original non-secret photo artifact IDs in data.related_ids. Payload-hash-bound application-document customization checks also expose the exact created role-document ID. Payload-hash-bound submission-report checks expose the exact reported submission ID. Other receipt namespaces do not expose related IDs. Never repeat an uncertain create with a new key.

GET /api/v1/journey/get_job_hunt_operation

DECLARED PERMISSIONS

  • read:profile
  • read:applications
  • read:documents
  • read:campaigns
  • read:tasks
  • read:contacts
  • read:interviews
  • read:companies
  • read:calendar
View input, output and access requirements →