Grammarly API Reliability

Grammarly API Reliability

This is a read-only, metadata-only decision aid for asynchronous Grammarly jobs. It does not call Grammarly, upload text, inspect a response body, create a token, or retry a request. It turns one strict JSON receipt into a bounded, evidence-labeled classification.

Overview

Use this skill to classify a sanitized asynchronous receipt without treating a provider response as permission to retry blindly.

Prerequisites

No credentials, network access, Grammarly account, document, or response body is needed. Python 3.10+ is the only runtime requirement. If a separate live integration is being designed, use the official OAuth 2.0 credentials documentation (accessed 2026-09-04) to determine access; live authentication and requests are outside this skill.

Instructions

Step 1: Run the deterministic analyzer

Run the bundled script against a receipt file or standard input:

python3 scripts/analyze_job_receipt.py receipt.json
cat receipt.json | python3 scripts/analyze_job_receipt.py -
python3 scripts/analyze_job_receipt.py --self-test

The analyzer accepts only the documented metadata schema in references/receipt-schema.md. It recursively rejects keys associated with document content, bodies, text, headers, or tokens, including those hidden in an otherwise unknown nested object. Unknown keys, malformed values, inconsistent 429 evidence, and attempts above the cap fail closed.

Step 2: Apply the decision rules

• COMPLETED is terminal. Do not retry it.
• PENDING is not a failure. Report that the receipt is still pending; do not invent a polling interval, timeout, SLA, quota, or freshness guarantee.
• FAILED with http_status: 429 is the only status-specific retry class in this skill. If a numeric retry_after_seconds value is supplied, the output preserves that evidence as the wait instruction. If it is absent, the output names Grammarly's documented 2-second-base exponential-backoff guidance for 429 only; it does not invent a maximum, jitter rule, quota, or service promise.
• Any failure without 429 evidence is MANUAL_REVIEW: the receipt alone does not establish that retrying is safe.
• A failed receipt at attempts == max_attempts is ATTEMPT_CAP_REACHED and must not receive retry guidance. An input with attempts > max_attempts is invalid.

The cap is caller-supplied policy, not a Grammarly limit. The analyzer never changes the cap or performs the next attempt. A human or caller-owned controller must decide whether a retry is appropriate after reviewing the emitted classification.

Step 3: Enforce the safety boundaries

Use synthetic receipts for evaluation. Never paste document text, raw request or response bodies, HTTP headers, access tokens, authorization values, or secrets. The script is standard-library-only and has no network, filesystem-write, subprocess, or deletion behavior. It reports validation errors rather than trying to sanitize unsafe input.

Read the focused references only when needed:

• references/receipt-schema.md — exact accepted fields, recursive rejection rules, and output classes.
• references/official-contract.md — the primary Grammarly Writing Score contract and the narrow 429 guidance boundary.

Output

The JSON result names the accepted status, attempts, cap, classification, and a short evidence-bounded guidance string. It never echoes submitted metadata beyond those safe scalar fields and never fabricates an SLA, timeout, quota, result body, or document diagnosis.

Error Handling

Invalid JSON, forbidden recursive keys, unknown fields, unsupported statuses, contradictory 429 evidence, and cap violations are errors. The script exits non-zero and emits no classification. A valid non-429 failure is MANUAL_REVIEW, not a retry recommendation.

Examples

• A completed receipt returns COMPLETED_TERMINAL and no retry instruction.
• A failed 429 with retry_after_seconds: 17 returns RETRY_AFTER_EVIDENCE and preserves 17 seconds.
• A nested diagnostics.response_body or credentials.access_token field is rejected before classification.

Resources

• references/receipt-schema.md — accepted fields, recursive rejection, and classifications.
• references/official-contract.md — primary Grammarly contract and narrow 429 guidance.
• Grammarly Writing Score API (accessed 2026-09-04).

Official source

Grammarly Writing Score API (accessed 2026-09-04).