Sudoku API limits & errors

Use HTTP status codes for request handling and the structured error body for details.

Request limits

Maximum 20 puzzles per request and 16 KiB JSON request bodies.
60 authenticated API requests per account per minute, shared across that account’s keys and REST/MCP. Additional per-instance limits protect the service.
Up to five active API keys per account. Revocation takes effect on subsequent requests.
PDF download grants last 24 hours. Download requests have a separate 60-per-account-per-minute limit plus shared protection.
Generation and uniqueness checking have bounded work budgets. The API never treats an unfinished search as proof of uniqueness.

Error format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Input did not match the schema.",
    "issues": [
      {
        "path": "count",
        "message": "Too big: expected number to be <=20"
      }
    ]
  }
}

Status reference

400

INVALID_REQUEST / INVALID_JSON

Check field names, types, allowed values and JSON syntax. Schema errors include issues with a path and message.

401

API_KEY_REQUIRED / INVALID_API_KEY

Send a valid API key in the Authorization header. Never put it in the query string.

403

ACCESS_DISABLED / DOWNLOAD_UNAVAILABLE

The key or account is disabled, or the PDF grant is invalid or expired. Use an active key and re-export the PDF.

404

NOT_FOUND / INVALID_LINK

Check the operation name or complete versioned link identifier.

405

METHOD_NOT_ALLOWED

Use the method listed in the Allow header. Operation endpoints accept POST; PDF downloads accept GET.

413

BODY_TOO_LARGE

Reduce the JSON request body to 16 KiB or less.

415

UNSUPPORTED_MEDIA_TYPE

Send Content-Type: application/json.

422

NOT_UNIQUE / SEARCH_LIMIT

A supplied grid could not be verified unique. Use /check to inspect the exact status.

429

RATE_LIMITED

Wait for the number of seconds in Retry-After before trying again.

500

INTERNAL_ERROR

The request could not be completed. Retry later; avoid tight retry loops.

503

GENERATION_LIMIT / ACCOUNTS_UNAVAILABLE

Try a smaller batch or wait until the service is available.

Retries and idempotency

On 429, honor Retry-After. Use bounded retries with backoff for temporary failures. Generating again may return different puzzles: /generate and /packs have no idempotency-key support. Keep successful responses instead of generating the same batch again.

Publishing the same grids produces the same playable links. Re-exporting creates a new PDF download grant and expiration.

Authentication and cross-origin access

Send Authorization: Bearer YOUR_API_KEY on REST and MCP requests. The REST API supports CORS preflight with Authorization. Keep API keys on your own server rather than shipping them in browser code or a mobile binary.

MCP accepts browser origins configured by the operator; other origins receive 403. Server-side MCP clients without an Origin header can connect normally. Developer-account actions require same-origin browser sessions.

Manage API keys →