Errors

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."
  }
}

The routes documented here return the following status and code families.

A 502 or 504 with no JSON error envelope comes from the gateway in front of the application, not from a Scry handler: the SQL is not at fault and rewriting it changes nothing, but whether the statement ran is unknown — a 502 is a refused connection or a broken reply, a 504 a reply that did not arrive in time, and either can land after the engine began work. Name the intent (idempotency-key header, MCP idempotency_key) and the retry answers for itself: if the first attempt settled, the door returns intent_settled with its query_id, row_count, and spend_nanodollars instead of running it again; if it never ran, it runs once. https://status.scry.io reports disruptions independently of the API.

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.