Errors
Every error is JSON with a stable machine-readable code and a human-readable message. Branch on the code, show the message.
The envelope
{
"error": {
"code": "quota_exceeded",
"message": "This check needs 720 credits; 300 remain. Buy a credit pack from your account."
}
}code is stable and safe to branch on. message is written for a person and may change; show it, do not parse it. Throttled responses also carry a Retry-After header in seconds.
Codes
| Status | Code | Family | Meaning |
|---|---|---|---|
| 400 | invalid_body | Request | The body failed validation; the message names the field. |
| 400 | invalid_view | Request | view was not summary or full. |
| 400 | invalid_json | Request | The body was sent as JSON but does not parse. |
| 400 | invalid_options | Request | options was not valid JSON, named a key the API does not know, or held a value of the wrong type; the message names the key. |
| 400 | invalid_citation_style | Request | citationStyle was not APA, MLA or Chicago. |
| 400 | invalid_include | Request | include named a report part that does not exist; the message lists the parts. |
| 400 | invalid_cursor | Request | cursor on GET /v1/checks was not the nextCursor of a previous page. |
| 400 | invalid_idempotency_key | Request | The Idempotency-Key header was empty or over 200 characters. |
| 400 | invalid_source_rule | Request | A source rule failed validation; the message names the field. |
| 400 | no_checks_selected | Request | Every pass in options was off; turn on at least one. |
| 400 | no_input | Document | Neither text nor file was sent. |
| 400 | multiple_inputs | Document | Both text and file were sent; send one. |
| 400 | too_short, too_long | Document | The word count is outside the per-check range. Judged at submission, for files too. |
| 400 | unsupported_type | Document | The bytes are no format the API reads; the message lists what it does. |
| 400 | unreadable_file, invalid_file | Document | A supported format that could not be parsed: damaged, password-protected, or a scan with no readable text. |
| 400 | unsupported_language | Document | Written mostly in a script without spaces between words. |
| 413 | file_too_large | Document | Over the upload cap; the message says the cap. |
| 401 | unauthorized, invalid_api_key | Auth | Missing, unknown or revoked key. |
| 403 | insufficient_scope | Auth | The key lacks the scope this call needs. |
| 403 | key_not_permitted | Auth | The endpoint is not part of the public API. |
| 402 | quota_exceeded, no_active_plan | Billing | Not enough credits for this check. |
| 402 | payment_past_due | Billing | The plan's last payment failed; plan checks resume once the card is updated. |
| 404 | not_found | Lookup | No such check on this account. |
| 409 | concurrent_limit | Throttle | Too many checks in flight; wait for one or cancel it. |
| 409 | still_running | State | You tried to delete a check that has not finished. |
| 409 | already_final | State | You tried to cancel a check that already finished. |
| 429 | rate_limited | Throttle | Too many requests; honor Retry-After. |
| 5xx | internal | Server | Something broke on our side. Safe to retry with backoff. |
Refusals never cost credits
A 400, 402, 413 or 429 at submission means no check was created and nothing was charged. A check that reaches rejected or failed after acceptance releases its credit reservation too, and its rejection.code says why.
Idempotent retries
A network failure after POST /v1/checks leaves you unsure whether the check was created. Send an Idempotency-Key header and retry with the same key: the API answers the first check's id with Idempotent-Replayed: true and never starts or charges a second check. See Idempotent requests.
Credits and limits
How usage is metered in credits, what a document may contain, and the per-key rate limits with what the API answers at each edge.
Guides
The patterns behind a solid Silvertext integration: the check lifecycle, choosing checks, source rules, reading the report, files, idempotent retries and rate limits.