Errors

Response format

All error responses share this shape:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  },
  "meta": {
    "api_version": "v1",
    "request_id": "req_xxxxxxxx"
  }
}

Always log the request_id

Include meta.request_id in your application logs. When you email support@skyden.app about a failing call, the request_id lets us find the exact request in our logs in seconds.

Common error codes

Code	Status	Description
MISSING_API_KEY	401	No Authorization: Bearer header
INVALID_API_KEY	401	Bearer key does not match any active key
INSUFFICIENT_SCOPE	403	API key lacks the required scope
RATE_LIMITED	429	Too many requests. Wait for the Retry-After header
INVALID_TOKEN	400	Linking token invalid, expired, or already used
PILOT_NOT_FOUND	404	Pilot not linked (never linked, or disconnected)
INVALID_REQUEST	400	Malformed request body or query parameters (e.g. oversized body on /v1/link, invalid UUID on the batch endpoint)
NOT_FOUND	404	Unknown endpoint path
METHOD_NOT_ALLOWED	405	HTTP method not supported by this endpoint (e.g. GET on /v1/link)
INTERNAL_ERROR	500	Server error. Email support@skyden.app with the request_id

Handling rate limits

A 429 response includes a Retry-After: 60 header (seconds). Back off for that duration before retrying. If you consistently hit the limit, email support@skyden.app to discuss a higher tier.