Skip to content

Error Codes

Every error response uses a consistent envelope:

{
"success": false,
"message": "Human-readable description",
"code": "machine_readable_code",
"errors": []
}

The code field is stable. Use it for programmatic error handling. The message field may change between versions.


Status Meaning Retryable?
400 Bad request. Invalid input No
401 Unauthorized. Missing or invalid API key or OAuth token No
403 Forbidden. Access denied, missing scope, a credential type the route doesn’t accept, plan limit exceeded, or CSRF failure (session auth only) No (check code)
404 Not found. Resource doesn’t exist No
409 Conflict. Resource state prevents the action No (fix state first)
415 Unsupported media type. A login request body that isn’t application/json No (fix input)
422 Validation error. Request body/query failed schema validation No (fix input)
429 Rate limited. Too many requests Yes (after Retry-After seconds)
500 Internal error. Unexpected server failure Yes

These can occur on any endpoint.

Code Status Description
bad_request 400 Request is malformed or semantically invalid.
unauthorized 401 No valid API key or OAuth token provided, or it has been revoked or has expired. Authentication gives the WWW-Authenticate header value.
forbidden 403 Access denied.
insufficient_scope 403 The API key or OAuth token lacks the scope the endpoint needs. required_scopes in the body and the WWW-Authenticate header name it. See Scopes.
credential_not_accepted 403 The credential is valid, but the route doesn’t accept its type: an API key or OAuth token on a dashboard-only route, or an OAuth token on worker claim or result.
insufficient_role 403 Dashboard only. Your role in the workspace is below what the action needs.
not_found 404 Resource does not exist or URL does not match any route.
conflict 409 Resource state prevents the requested action.
unsupported_media_type 415 POST /auth/code, POST /auth/code/verify, or POST /auth/register received a body that isn’t application/json.
validation_error 422 Request body, query, or path params failed schema validation. A field that contains a NUL character (U+0000) or an unpaired UTF-16 surrogate fails too, with the message <field> must not contain NUL characters or unpaired surrogates. See errors array for details.
rate_limit_exceeded 429 Exceeded the rate limit (approximately 100 requests per 10 seconds per client IP, with an IPv6 client counted by its /64 network). The Retry-After header tells you when to retry.
internal_error 500 Unexpected server error.
error Other Code for a status that has no specific code above. A 500 carries internal_error.

Code Status When
schedule_not_found 404 Schedule ID doesn’t exist or doesn’t belong to your workspace.
schedule_archived 409 Attempting to update, trigger, pause, resume, or re-archive an archived schedule.
schedule_completed 409 Attempting to update, trigger, pause, or resume a completed schedule (reached runs limit or stop_at).
schedule_already_paused 409 Pausing a schedule that is already paused.
schedule_already_active 409 Resuming a schedule that is already active.
schedule_cadence_invalid 422 Resuming a schedule whose stored cron, interval, or timezone can no longer be computed. Update the schedule, then resume.
handler_required_for_pull 400 Updating a schedule to pull delivery without setting a handler.
schedule_status_changed 409 Concurrent update detected. The schedule’s status changed between your read and write. Retry the operation.
plan_limit_exceeded 403 The request exceeds a plan limit: the active-schedule count (create, resume), the timeout cap (create, update, resume, trigger), or the minimum interval (create, update, resume). The message names the limit and your tier; see Pricing & Limits.

Code Status When
job_not_found 404 Job ID doesn’t exist or doesn’t belong to your workspace.
idempotency_key_conflict 409 A job with the same idempotency_key already exists in your workspace.
job_not_cancellable 409 Cancelling a job that isn’t pending, admitting, queued, ready, or retrying.
job_not_scheduled 409 Skipping a one-off job. Only schedule-spawned jobs can be skipped.
job_not_skippable 409 Skipping a job that isn’t pending or queued.
job_not_failed 409 Retrying a job that hasn’t failed.
job_status_changed 409 Concurrent update detected. The job’s status changed between your read and write. Retry the operation.
plan_limit_exceeded 403 timeout exceeds your plan’s cap. The message names the cap and your tier; see Pricing & Limits.

Code Status When
execution_not_found 404 Execution ID doesn’t exist or doesn’t belong to your workspace.
execution_not_running 409 Reporting a result for an execution that isn’t in running status. The execution may have already timed out or been reported by another process. Reporting the status the execution already has returns 200 instead.
plan_limit_exceeded 403 Claiming a job after your plan’s monthly execution quota is used up. See Pricing & Limits.

Code Status When
monitor_not_found 404 Monitor ID doesn’t exist or doesn’t belong to your workspace.
monitor_already_paused 409 Pausing a monitor that is already paused.
monitor_not_paused 409 Resuming a monitor that isn’t paused.
plan_limit_exceeded 403 Creating or resuming a monitor when you already have as many active monitors as your plan allows. See Pricing & Limits.

The Ping API returns plain-text responses, not these codes.


Code Status When
signing_key_not_found 404 No signing key exists for your workspace. Contact support@chronos.sh.
signing_key_grace_window_active 409 A key rotation is already in progress. Wait 24 hours for the grace window to close before rotating again.

When the code is validation_error, the errors array contains per-field details:

{
"success": false,
"message": "request body failed validation",
"code": "validation_error",
"errors": [
{
"field": "cron",
"message": "cron must be a valid cron expression"
},
{
"field": "payload",
"message": "payload must be 64KB or smaller"
}
]
}

Common validation messages:

Message Cause
provide either cron or interval, not both Schedule creation/update with both timing fields
provide either delay or scheduled_for, not both Job creation with both timing options
payload must be 64KB or smaller Payload exceeds size limit
cron must be a valid cron expression Unparseable cron syntax
must be a valid IANA timezone Invalid timezone string
url must use https in production HTTP URL (HTTPS required in production)
url must not point to a private or reserved IP address Localhost or private network URL
stop_at must be a future date Past date for schedule termination
scheduled_for must be a future date Past date for job execution
size must be between 1 and 100 Pagination page size out of range
at least one field must be provided Empty update body
cron must not be more frequent than every 60 seconds Monitor cron expression that fires more often than once a minute
interval must not be more frequent than every 60 seconds Monitor interval under 60 seconds
cron must fire at least twice in the next 2 years Monitor cron expression that fires too rarely
interval must not be longer than 365 days Monitor interval over 365 days
grace_seconds must be between 60 and 604800 Monitor grace period out of range

The SDK throws API errors as typed error classes. Resource methods throw ChronosApiError, so branch on its code:

import { Chronos, ChronosApiError } from '@chronos.sh/sdk';
const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY! });
try {
await chronos.jobs.create({
name: 'Charge invoice inv_789',
handler: 'charge-invoice',
idempotency_key: 'charge-inv_789',
});
} catch (err) {
if (!(err instanceof ChronosApiError)) throw err;
switch (err.code) {
case 'idempotency_key_conflict':
break; // The job already exists.
case 'validation_error':
console.error('Invalid input:', err.fieldErrors);
break;
default:
throw err;
}
}

Reads retry network errors, timeouts, 429 and 5xx responses before throwing, and writes retry only on 429. The Node.js and Go SDK references give the full retry rule.

The worker retries 429 and 5xx responses itself. It stops, and start() rejects, on three errors that retrying can’t fix: a 401, a claim that gets insufficient_scope, and a claim that gets credential_not_accepted. Worker routes accept API keys only, and the key needs workers:run:

import { Chronos, ChronosApiError, ChronosAuthenticationError } from '@chronos.sh/sdk';
const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY! });
try {
await chronos.worker.start();
} catch (err) {
if (err instanceof ChronosAuthenticationError) {
console.error('Chronos rejected the API key; rotate CHRONOS_API_KEY', { requestId: err.requestId });
process.exit(1);
}
if (err instanceof ChronosApiError && err.code === 'insufficient_scope') {
console.error('Use an API key with the workers:run scope', { requestId: err.requestId });
process.exit(1);
}
if (err instanceof ChronosApiError && err.code === 'credential_not_accepted') {
console.error('CHRONOS_API_KEY holds an OAuth token; set it to an API key from Settings → Keys', { requestId: err.requestId });
process.exit(1);
}
throw err;
}

See the Node.js SDK reference and the Go SDK reference for the full list of errors.

Check the code field for programmatic handling:

const res = await fetch('https://api.chronos.sh/v1/schedules', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(schedule),
});
if (!res.ok) {
const error = await res.json();
switch (error.code) {
case 'validation_error':
console.error('Invalid input:', error.errors);
break;
case 'rate_limit_exceeded':
const retryAfter = res.headers.get('Retry-After');
await sleep(Number(retryAfter) * 1000);
break;
case 'unauthorized':
throw new Error('Check your API key');
break;
}
}