Error codes

Every Skryx error is a stable code you can branch on.

Skryx never exposes raw exception messages to API consumers. Instead, every failure carries a stable SK-* code plus an INC-… incident ID you can reference in support requests.

# Response shape

{
  "error": {
    "code": "SK-AI-503",
    "message": "AI features are temporarily unavailable. Please try again in a few minutes.",
    "incident_id": "INC-A4B2C3D8"
  }
}

The message is safe to surface directly to end users; it's localised when your request includes Accept-Language: ro. The incident_id is the reference admin support uses to look up the full diagnostics.

# Code catalogue

# AI module

Code Status Meaning
SK-AI-503 503 AI provider is unavailable. Search still works (falls back to keyword).
SK-AI-429 429 Monthly AI quota exhausted. Upgrade the plan or wait.
SK-AI-422 422 AI returned an unparseable response. Retry.
SK-AI-504 504 AI call timed out. Retry.

# Search module

Code Status Meaning
SK-SE-503 503 Search engine is unavailable. Usually a brief blip — retry with backoff.
SK-SE-400 400 Invalid query (missing q, bad filter_by syntax).
SK-SE-504 504 Search took too long. Try a more specific query or narrower filter.
SK-SE-404 404 Index does not exist or your key can't access it.

# Data sources

Code Status Meaning
SK-DS-503 503 Could not reach the data-source URL.
SK-DS-422 422 Format unsupported or feed contains errors.
SK-DS-504 504 Data source timed out.
SK-DS-401 401 Auth to the data source failed.

# System

Code Status Meaning
SK-SYS-500 500 Internal error. We've been notified.
SK-SYS-503 503 Skryx is in maintenance.
SK-SYS-429 429 Too many requests. Honour the Retry-After header.

# Retry guidance

Code prefix Retry?
SK-AI-* (except 429) Yes, with backoff. Cap retries at 3.
SK-SE-503 / SK-SE-504 Yes, with backoff.
SK-SE-400 / SK-SE-404 No — fix the request.
SK-DS-401 / SK-DS-422 No — fix the feed or credentials.
SK-SYS-429 Yes, after Retry-After seconds.

# When something is weird

Send the INC-… ID to support@skryx.io and we'll dig out the full trace from the admin incidents panel.

esc