Docs
Errors
Handle Scry HTTP error envelopes, status codes, retry guidance, and long-query failures.
Error shape
Application errors emitted by Scry handlers use JSON shaped as {"error":{"code":"...","message":"...","details":...}}. The details field is omitted when the error has no structured detail. Retryable responses can include the Retry-After header. Framework-level JSON parsing failures can use a different response shape.
{
"error": {
"code": "invalid_request",
"message": "Missing Content-Type. Use text/plain, text/sql, application/sql, or application/json."
}
} Status codes
The routes documented here return the following status and code families.
| Status | Codes and meaning |
|---|---|
| 400 | `invalid_request` for unsupported content types, invalid SQL, or endpoint validation failures. JSON extractor failures can use a framework response. |
| 401 | `unauthorized` when the bearer credential is missing, malformed, or invalid. |
| 402 | `insufficient_credits` or the query payment challenge when funds or payment authorization are required. |
| 403 | `forbidden` when account state or key scope denies the request. |
| 405 | `method_not_allowed`; the SQL route also returns `Allow: POST, QUERY`. |
| 408 | `request_timeout` or `runtime_deadline_exceeded` when execution exceeds its deadline. |
| 409 | `conflict` when a web-search wallet reservation is already closed. |
| 429 | `rate_limited`, `query_capacity_exhausted`, or `auction_not_cleared`; inspect `Retry-After`. |
| 500 | `internal_error` when the server cannot complete internal work. |
| 503 | `service_unavailable` when an endpoint, provider set, admission channel, or dependency is unavailable. |
Long queries
After the synchronous grace period, the SQL route can begin a 200 application/json stream and send whitespace while execution continues. A later failure then appears as the same JSON error object inside that 200 response because the HTTP status has already been sent. Check the body for error before treating a long-query response as a result.