Troubleshooting for developers
The error messages the delivery API, management API, GraphQL, the SDKs, webhooks and the MCP server give, and common symptoms, each with the cause and the fix.
Reference9 min read
Find the message or symptom, then the cause and the fix. The API playground is the quickest way to see what the API answers for a given key and address.
Every API error is JSON: { "error": { "code": "…", "message": "…" } }. Messages to candidates come in the language of the request.
Keys and tokens
Send your public key as a Bearer token. Create one under API keys in Careers Orbit.Cause
A delivery or GraphQL call without a key
Fix
Send
Authorization: Bearer careers_pk_..., X-Api-Key or ?key=This API key isn't valid. Check it under API keys in Careers Orbit.Cause
A typo, a key from another environment, or a management token sent to the delivery API
Fix
Copy the key again. Staging and production have their own keys.
This API key has been revoked. or This API key has expired.Cause
An admin revoked it, or its expiry date passed
Fix
Create a new key under API keys
Send a management token as a Bearer token. Create one under API keys in Careers Orbit.Cause
A management API call without a token
Fix
Send
Authorization: Bearer careers_mt_...This management token isn't valid., has been revoked. or has expired.Cause
A typo, a public key sent to the management API, or a token that was revoked or ran out
Fix
Create a new token. Tokens last at most a year.
The person this token belongs to no longer has Careers Orbit in this organisation.Cause
The token's person left or lost Careers Orbit in Orbit
Fix
An admin who stays creates a new token
This token only reads. Create one that may change things under API keys.Cause
A change with a read-only token
Fix
Create a token with Read only off
The management API is not in the Careers Orbit Starter plan. …Cause
The management API and webhooks need Growth or Enterprise
Fix
An owner upgrades under Billing in Orbit
| Message | Cause | Fix |
|---|---|---|
Send your public key as a Bearer token. Create one under API keys in Careers Orbit. | A delivery or GraphQL call without a key | Send Authorization: Bearer careers_pk_..., X-Api-Key or ?key= |
This API key isn't valid. Check it under API keys in Careers Orbit. | A typo, a key from another environment, or a management token sent to the delivery API | Copy the key again. Staging and production have their own keys. |
This API key has been revoked. or This API key has expired. | An admin revoked it, or its expiry date passed | Create a new key under API keys |
Send a management token as a Bearer token. Create one under API keys in Careers Orbit. | A management API call without a token | Send Authorization: Bearer careers_mt_... |
This management token isn't valid., has been revoked. or has expired. | A typo, a public key sent to the management API, or a token that was revoked or ran out | Create a new token. Tokens last at most a year. |
The person this token belongs to no longer has Careers Orbit in this organisation. | The token's person left or lost Careers Orbit in Orbit | An admin who stays creates a new token |
This token only reads. Create one that may change things under API keys. | A change with a read-only token | Create a token with Read only off |
The management API is not in the Careers Orbit Starter plan. … | The management API and webhooks need Growth or Enterprise | An owner upgrades under Billing in Orbit |
Delivery API and GraphQL
This website isn't allowed to use the key. … (403)Cause
A browser call from a website missing from Allowed websites
Fix
Add the exact origin, such as
https://northwilds.com, under Career site › Address and website. https://www.northwilds.com is a different origin.A CORS error in the browser, with no answer
Cause
The same, seen from the browser. Without an allowed origin, no
Access-Control-Allow-Origin comes backFix
As above, or call the API from your server
Job was not found (404)Cause
The job is closed, scheduled, unpublished, internal-only for a key that can't read internal jobs, or its address changed
Fix
Use GET
/jobs or GET/sitemap for the live slugs. Use findJob in the SDKs to get null instead of an error.The privacy notice has just changed. Reload the page and read it again. (400)Cause
The application or sign-up sent an older
privacyVersionFix
Read the job or GET
/site again and show the new noticeThese career pages are paused … (402, subscription_inactive)Cause
The trial or plan ended, so Careers Orbit is paused
Fix
An owner chooses a plan under Billing in Orbit
That file is larger than 10 MB. or Choose a PDF or Word file. (400)Cause
A CV or file that is too large, or not a PDF or Word document
Fix
Check the size and type before sending
<Question>: … (400), or 422 with issuesCause
A required field or answer is missing, or a choice isn't one of the options
Fix
Build the form from the job's
form. Send option ids, not labels.Too many tries. Wait a minute and try again. (429)Cause
More than about 120 reads a minute for one key and network, or more than six applications in a burst
Fix
Cache reads on your server. Don't send test applications in a loop.
query_too_large, query_too_deep, query_too_complex (GraphQL)Cause
A query over 20,000 characters, 10 levels or 300 fields
Fix
Split it into smaller queries
Something went wrong on our side. Try again in a moment. (500)Cause
A failure in Careers Orbit
Fix
Try again. The SDKs retry reads twice.
This service is restarting or not available right now. (503, unavailable)Cause
Careers Orbit is restarting after an update
Fix
Try again after a few seconds
| Message or status | Cause | Fix |
|---|---|---|
This website isn't allowed to use the key. … (403) | A browser call from a website missing from Allowed websites | Add the exact origin, such as https://northwilds.com, under Career site › Address and website. https://www.northwilds.com is a different origin. |
| A CORS error in the browser, with no answer | The same, seen from the browser. Without an allowed origin, no Access-Control-Allow-Origin comes back | As above, or call the API from your server |
Job was not found (404) | The job is closed, scheduled, unpublished, internal-only for a key that can't read internal jobs, or its address changed | Use GET/jobs or GET/sitemap for the live slugs. Use findJob in the SDKs to get null instead of an error. |
The privacy notice has just changed. Reload the page and read it again. (400) | The application or sign-up sent an older privacyVersion | Read the job or GET/site again and show the new notice |
These career pages are paused … (402, subscription_inactive) | The trial or plan ended, so Careers Orbit is paused | An owner chooses a plan under Billing in Orbit |
That file is larger than 10 MB. or Choose a PDF or Word file. (400) | A CV or file that is too large, or not a PDF or Word document | Check the size and type before sending |
<Question>: … (400), or 422 with issues | A required field or answer is missing, or a choice isn't one of the options | Build the form from the job's form. Send option ids, not labels. |
Too many tries. Wait a minute and try again. (429) | More than about 120 reads a minute for one key and network, or more than six applications in a burst | Cache reads on your server. Don't send test applications in a loop. |
query_too_large, query_too_deep, query_too_complex (GraphQL) | A query over 20,000 characters, 10 levels or 300 fields | Split it into smaller queries |
Something went wrong on our side. Try again in a moment. (500) | A failure in Careers Orbit | Try again. The SDKs retry reads twice. |
This service is restarting or not available right now. (503, unavailable) | Careers Orbit is restarting after an update | Try again after a few seconds |
Management API
The cursor isn't valid. Use meta.next from the page before.Cause
A made-up or cut-off
cursorFix
Send
meta.next exactlyupdatedSince must be a date, such as 2026-10-01T00:00:00ZCause
A date in another format
Fix
Send ISO 8601
status must be open or one of …Cause
An unknown job status in GET
/jobsFix
Use
open, draft, inReview, published, internal, closed or archivedThat stage isn't in this job's pipeline. GET /stages lists them.Cause
A
stageId from another pipelineFix
Read the job's pipeline from GET
/stagesUse POST /applications/{id}/reject, with a reason, to rejectCause
A move to the rejected stage
Fix
Call
/reject with a reasonIdJob ads are reviewed before they go live here. Send it for review.Cause
Your organisation reviews job ads first
Fix
A person sends the job for review in Careers Orbit
Your Careers Orbit … plan includes … active jobs. …Cause
Publishing would go over the plan's live jobs
Fix
Close a job first, or upgrade
Careers Orbit is paused since the trial ended …Cause
The trial or plan ended
Fix
Reading and moving candidates still work. An owner chooses a plan.
Your Careers Orbit role doesn't allow that. Ask an admin of your organisation.Cause
The token's person may not do this, such as a hiring manager on another team's job
Fix
Use a token created by someone with the right role
| Message | Cause | Fix |
|---|---|---|
The cursor isn't valid. Use meta.next from the page before. | A made-up or cut-off cursor | Send meta.next exactly |
updatedSince must be a date, such as 2026-10-01T00:00:00Z | A date in another format | Send ISO 8601 |
status must be open or one of … | An unknown job status in GET/jobs | Use open, draft, inReview, published, internal, closed or archived |
That stage isn't in this job's pipeline. GET /stages lists them. | A stageId from another pipeline | Read the job's pipeline from GET/stages |
Use POST /applications/{id}/reject, with a reason, to reject | A move to the rejected stage | Call /reject with a reasonId |
Job ads are reviewed before they go live here. Send it for review. | Your organisation reviews job ads first | A person sends the job for review in Careers Orbit |
Your Careers Orbit … plan includes … active jobs. … | Publishing would go over the plan's live jobs | Close a job first, or upgrade |
Careers Orbit is paused since the trial ended … | The trial or plan ended | Reading and moving candidates still work. An owner chooses a plan. |
Your Careers Orbit role doesn't allow that. Ask an admin of your organisation. | The token's person may not do this, such as a hiring manager on another team's job | Use a token created by someone with the right role |
SDKs
apiUrl is required, such as https://api.bifrostorbit.com/careers/v1Cause
CAREERS_API_URL is not set where the code runs, including during next buildFix
Set it for builds and for running
publicKey must be a Careers Orbit public key, starting with careers_pk_Cause
An empty key, or a management token in the website
Fix
Use a public key. Management tokens never belong in a website.
The webhook secret is requiredCause
createRevalidateHandler without CAREERS_WEBHOOK_SECRETFix
Set the secret shown when you set the website webhook
Bad signature (401 from your revalidate route)Cause
The secret in your website doesn't match, or the body was changed before checking
Fix
Copy the secret again. Check the raw body, before any JSON parsing.
The message is too old (401)Cause
The server's clock is off by more than five minutes, or an old message was replayed
Fix
Sync the server's clock
That code isn't right. or That code has expired. Ask for a new one. (portal)Cause
A wrong code, more than five tries, or a code older than ten minutes
Fix
Ask for a new code. A new one can be sent every 45 seconds.
Sign in with the code we email you. (401, portal)Cause
No session, or one older than two hours
Fix
Sign in again. The SDKs clear the stored session.
CareersSubscriptionInactiveError (402, subscription_inactive)Cause
The organisation's Careers Orbit trial or plan has ended, so the career site is paused
Fix
Nothing to fix in the code: show a calm "temporarily unavailable" page with your own name, checked with
isSubscriptionInactive(error). The PHP, Swift and Kotlin SDKs have their own paused error. Jobs come back as soon as an owner chooses a plan.| Message | Cause | Fix |
|---|---|---|
apiUrl is required, such as https://api.bifrostorbit.com/careers/v1 | CAREERS_API_URL is not set where the code runs, including during next build | Set it for builds and for running |
publicKey must be a Careers Orbit public key, starting with careers_pk_ | An empty key, or a management token in the website | Use a public key. Management tokens never belong in a website. |
The webhook secret is required | createRevalidateHandler without CAREERS_WEBHOOK_SECRET | Set the secret shown when you set the website webhook |
Bad signature (401 from your revalidate route) | The secret in your website doesn't match, or the body was changed before checking | Copy the secret again. Check the raw body, before any JSON parsing. |
The message is too old (401) | The server's clock is off by more than five minutes, or an old message was replayed | Sync the server's clock |
That code isn't right. or That code has expired. Ask for a new one. (portal) | A wrong code, more than five tries, or a code older than ten minutes | Ask for a new code. A new one can be sent every 45 seconds. |
Sign in with the code we email you. (401, portal) | No session, or one older than two hours | Sign in again. The SDKs clear the stored session. |
CareersSubscriptionInactiveError (402, subscription_inactive) | The organisation's Careers Orbit trial or plan has ended, so the career site is paused | Nothing to fix in the code: show a calm "temporarily unavailable" page with your own name, checked with isSubscriptionInactive(error). The PHP, Swift and Kotlin SDKs have their own paused error. Jobs come back as soon as an owner chooses a plan. |
Webhooks
The log on each webhook's page shows why a delivery failed.
The endpoint answered 404 (or another status)Cause
Your endpoint refused it, or redirected it; redirects are not followed
Fix
Answer with 2xx at the exact address, without a redirect
No answer within 10 secondsCause
Your endpoint does its work before answering
Fix
Answer at once and do the work in the background
The endpoint could not be reachedCause
DNS, TLS or firewall
Fix
Check the address works from the internet over
https://The webhook shows Stopped after failures
Cause
20 failed deliveries in a row
Fix
Fix the endpoint, then choose Turn on and Send again
Notifications name candidates, so only a trusted webhook can receive themCause
careers.notification on an untrusted webhookFix
Turn on Trusted endpoint, if your privacy notice covers the system
| Error in the log | Cause | Fix |
|---|---|---|
The endpoint answered 404 (or another status) | Your endpoint refused it, or redirected it; redirects are not followed | Answer with 2xx at the exact address, without a redirect |
No answer within 10 seconds | Your endpoint does its work before answering | Answer at once and do the work in the background |
The endpoint could not be reached | DNS, TLS or firewall | Check the address works from the internet over https:// |
| The webhook shows Stopped after failures | 20 failed deliveries in a row | Fix the endpoint, then choose Turn on and Send again |
Notifications name candidates, so only a trusted webhook can receive them | careers.notification on an untrusted webhook | Turn on Trusted endpoint, if your privacy notice covers the system |
MCP server
Connect the assistant to Careers Orbit againCause
The assistant's token was revoked or its refresh token ran out
Fix
Connect it again from the assistant
The person who connected this assistant no longer has Careers Orbit in the organisationCause
The person lost access in Orbit
Fix
Someone with access connects it
Assistants only write in draft job ads. …Cause
A change to a job that isn't a draft
Fix
Use
create_job_draft for a new version| Message | Cause | Fix |
|---|---|---|
Connect the assistant to Careers Orbit again | The assistant's token was revoked or its refresh token ran out | Connect it again from the assistant |
The person who connected this assistant no longer has Careers Orbit in the organisation | The person lost access in Orbit | Someone with access connects it |
Assistants only write in draft job ads. … | A change to a job that isn't a draft | Use create_job_draft for a new version |
Symptoms
A closed job stays on your website
Cause
Pages are cached and the website webhook is not set, or fails
Fix
Set it under Settings › Website webhook and check your route answers 2xx. Delivery reads may be cached for 60 seconds.
Job links in emails and Google point at the hosted pages
Cause
Job addresses is empty
Fix
Set it under Career site › Address and website
German text shows in English
Cause
That field has no German translation yet
Fix
Fields fall back one by one;
fallback lists themAn internal job is missing
Cause
The key can't read internal jobs
Fix
Use a key with Read internal-only jobs, on a server
Every call gets 402
subscription_inactiveCause
The trial or plan ended
Fix
An owner chooses a plan
Views don't show in Reports
Cause
The track call came with no user agent, or one that looks like a bot or script (such as curl or python), or for a job that isn't live
Fix
Count views from the visitor's browser or app
| Symptom | Cause | Fix |
|---|---|---|
| A closed job stays on your website | Pages are cached and the website webhook is not set, or fails | Set it under Settings › Website webhook and check your route answers 2xx. Delivery reads may be cached for 60 seconds. |
| Job links in emails and Google point at the hosted pages | Job addresses is empty | Set it under Career site › Address and website |
| German text shows in English | That field has no German translation yet | Fields fall back one by one; fallback lists them |
| An internal job is missing | The key can't read internal jobs | Use a key with Read internal-only jobs, on a server |
Every call gets 402 subscription_inactive | The trial or plan ended | An owner chooses a plan |
| Views don't show in Reports | The track call came with no user agent, or one that looks like a bot or script (such as curl or python), or for a job that isn't live | Count views from the visitor's browser or app |
Was this page helpful?
Read next
Delivery APIRead published jobs, filters, your career site and a sitemap, and send applications, talent pool sign-ups, job views and candidate portal calls, with a public key.The management APIRead jobs, applications, candidates and stages, and move, reject and tag candidates, add notes and publish or close jobs, from your own scripts and systems with a management token.GraphQLRead your career site, jobs, one job, filters and the sitemap in one request, with the schema, examples, errors and limits.Webhooks and eventsSend signed webhooks to your own systems when jobs, applications, candidates, offers and postings change, refresh your website's job pages, and see which events Careers Orbit sends.API keysCreate public keys for the delivery API, so your website and the Careers SDK can read published jobs and send applications, and management tokens for scripts and other systems.