Errors

Platform API errors use a consistent JSON body and never include stack traces, SQL text, or secrets.

Envelope

{
  "error": {
    "type": "validation_error",
    "message": "Human-readable explanation.",
    "doc_url": "https://docs.scrapy.io/errors/validation-error"
  }
}

Field	Description
type	Stable machine-readable code
message	Safe human-readable text
doc_url	Link to this docs site for the error family

Types and HTTP status

type	HTTP	When
unauthorized	401	Missing or invalid API key
forbidden	403	Authenticated but not allowed (reserved)
not_found	404	Tool / run / schedule missing or not owned by you
validation_error	400	Bad query/body (pagination, schedule fields, …)
insufficient_credits	402	Not enough credits to create a schedule / start work
conflict	409	Idempotency key already in progress
rate_limit_exceeded	429	Too many requests (when rate limits apply)
internal_error	500	Unexpected server failure

Examples

Missing API key

curl -s "https://api.scrapy.infralyon.com/v1/tools"

{
  "error": {
    "type": "unauthorized",
    "message": "Authentication token was not provided",
    "doc_url": "https://docs.scrapy.io/errors/unauthorized"
  }
}

Invalid pagination

curl -s "https://api.scrapy.infralyon.com/v1/tools?limit=999" \
  -H "Authorization: Bearer $SCRAPY_API_KEY"

{
  "error": {
    "type": "validation_error",
    "message": "limit must be at most 100",
    "doc_url": "https://docs.scrapy.io/errors/validation-error"
  }
}

Unknown run

curl -s "https://api.scrapy.infralyon.com/v1/runs/00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer $SCRAPY_API_KEY"

{
  "error": {
    "type": "not_found",
    "message": "Run was not found",
    "doc_url": "https://docs.scrapy.io/errors/not-found"
  }
}

Handling errors in clients

1. Read HTTP status for coarse handling (401 refresh key, 402 top up credits, 429 backoff).
2. Read error.type for branching.
3. Show error.message to developers; link doc_url in logs/UI.
4. Retry only idempotent GETs, or POSTs that used Idempotency-Key.

Publisher execution errors

Errors from {publisher}.p.scrapy.infralyon.com may use a different body shape than Platform { error: { type, message, doc_url } }. Prefer Platform for run status after the job is created; treat publisher responses according to that tool’s Store API docs / snippets.

Related

• Authentication
• Platform overview