Errors

The Cron API uses standard HTTP status codes with a JSON body envelope. All error responses contain at least an error string. Validation failures (422) also include a details map with per-field error messages.

Status Codes

Status	Cause	Example body
401 Unauthorized	API key missing, malformed, or revoked	{"error": "Invalid or missing API key"}
403 Forbidden	API key lacks the required scope (cron:read for reads, cron:write for writes)	{"error": "Insufficient scope"}
404 Not Found	Job not found, or :id is not a valid UUID, or the job belongs to a different team	{"error": "Not found"}
422 Unprocessable Entity	Validation failed on the request body	{"error": "Validation failed", "details": {"schedule": ["is not a valid cron expression"]}}
429 Too Many Requests	Monthly platform usage limit exceeded — upgrade required	{"error": "Monthly usage limit exceeded. Upgrade your plan."}

Validation Error Examples

The details map echoes Ecto changeset errors. Common Cron validation messages:

{
  "error": "Validation failed",
  "details": {
    "name": ["can't be blank"],
    "url": ["can't be blank"],
    "schedule": ["can't be blank"]
  }
}

{
  "error": "Validation failed",
  "details": {
    "schedule": ["is not a valid cron expression"]
  }
}

{
  "error": "Validation failed",
  "details": {
    "schedule": ["is not a valid interval (must be one of: every_30s, every_1m, every_5m, every_15m, every_30m, every_1h, every_6h, every_12h, every_1d)"]
  }
}

{
  "error": "Validation failed",
  "details": {
    "schedule": ["must be a valid ISO 8601 datetime"]
  }
}

{
  "error": "Validation failed",
  "details": {
    "method": ["is invalid"]
  }
}

{
  "error": "Validation failed",
  "details": {
    "url": ["must be a valid http or https URL"]
  }
}

{
  "error": "Validation failed",
  "details": {
    "url": ["must not target private or internal addresses"]
  }
}

{
  "error": "Validation failed",
  "details": {
    "timezone": ["is not a valid IANA timezone"]
  }
}

{
  "error": "Validation failed",
  "details": {
    "timeout_ms": ["must be less than or equal to 300000"]
  }
}

Notes

• 403 Forbidden is also returned for cross-team access attempts when an API key without * scope tries to read or write a resource owned by another team.
• The details map only appears for changeset-derived validation errors. Atom-derived errors (e.g. :not_found, :limit_exceeded) return only error.
• See Authentication for how to obtain and use API keys, and Rate Limits for platform-wide request quotas.