Errors · cons

Request errors

When a request is turned away, the response has a 4xx or 5xx status and an error object with a type to match on and a human-readable message. Don't match on the message; it can change.

429 Too Many Requests

{
  "error": {
    "type": "rate_limited",
    "message": "rate limit of 60 requests per minute per key reached; retry in 12 s"
  },
  "request_id": "req_..."
}

Type	HTTP	Meaning
`invalid_json`	400	The body isn't valid JSON.
`invalid_request`	422	`source` is missing or not a string, or `timeout_ms` is out of range.
`unauthorized`	401	The key is missing, malformed, unknown or revoked.
`forbidden_origin`	403	A `/v1/demo` call that didn't come from the site.
`not_found`	404	No such endpoint.
`source_too_large`	413	The source is over the size limit.
`request_too_large`	413	The body is over 1 MB.
`rate_limited`	429	Too many requests this minute. Wait for `Retry-After` seconds.
`too_many_in_flight`	429	Too many evaluations running at once for the account.
`cpu_quota_exceeded`	429	This month's CPU allowance is used up. `Retry-After` is the time to the reset.
`busy`	503	Every evaluation slot is taken. Retry shortly. Nothing is charged.
`internal_error`	500	Something broke on our side.

Program errors

A program that fails still gets 200. status says how it ended, and error has the type, a message, and the form, line and column that failed. Results for the forms before it are kept.

200 OK

{
  "status": "error",
  ...
  "error": {
    "type": "unbound_variable",
    "message": "unbound variable: fib",
    "index": 0, "line": 1, "col": 1
  }
}

Type	`status`	Meaning
`syntax_error`	`error`	The source doesn't parse: unbalanced parentheses, a bad literal.
`unbound_variable`	`error`	A name that isn't defined.
`wrong_type`	`error`	An argument of the wrong type, like `(car 5)`.
`arity_mismatch`	`error`	A procedure called with the wrong number of arguments.
`not_a_procedure`	`error`	Calling something that isn't a procedure, like `(1 2)`.
`division_by_zero`	`error`	Dividing by zero, including floats.
`arithmetic_error`	`error`	Another arithmetic failure.
`user_error`	`error`	The program called `error`.
`timeout`	`timeout`	The wall-clock timeout ran out.
`step_limit`	`limit_exceeded`	The program ran out of evaluation steps.
`memory_limit`	`limit_exceeded`	The program used more memory than allowed.
`integer_too_large`	`limit_exceeded`	An integer grew past the size limit.
`too_complex`	`limit_exceeded`	The source has too many compound expressions.
`source_too_large`	`limit_exceeded`	The source is over the size limit.
`internal_error`	`error`	The evaluator failed. Please report it with the request id.

Retrying

rate_limited and too_many_in_flight: wait for the Retry-After header, then retry.
busy: retry after a short backoff. A busy request isn't charged.
cpu_quota_exceeded: requests fail until the month resets, or until you move to a paid plan.
Program errors with status error are deterministic: the same source fails the same way every time.