Errors

A failed request returns a non-2xx HTTP status with a JSON error body.

Error response shape

Confirmed error envelope (this application's own server-side integration code depends on this exact shape — see App\Services\AstroPlatform::unwrap()):

// non-2xx response
{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable description"
  }
}

Status codes

Standard HTTP status codes apply. Exact per-endpoint status/error-code combinations are documented in the full API reference rather than repeated here, so this page can't drift out of sync with it. In general:

Status	Typical meaning
`400` / `422`	The request body failed validation.
`401`	The `X-API-Key` header is missing, invalid, or the key has been revoked.
`403`	The key is valid but doesn't have the scope required for this endpoint, or your quota has been exceeded.
`404`	The endpoint or requested resource doesn't exist.
`429`	Too many requests — you've hit the per-second rate limit for your plan.
`500`	Something failed on the server side. Retry, and contact support if it persists.

Handling errors in code

Check the HTTP status first, then read error.message for a human-readable description — it's safe to display directly in most cases. Use error.code for programmatic handling (e.g. distinguishing a validation failure from a quota failure).