Errors

On this page

A refusal is JSON with one field that says what happened in a sentence, and a status code that says which kind of thing it was.

The shape

JSON

{ "error": "No published manual at this address." }

Every refusal is application/json, carries Cache-Control: no-store so it is never kept, and the same CORS headers as a success, so a browser can read it. The sentence is meant for a log; branch on the status code.

Status codes

401 Unauthorized

The manual is not public and no token came with the request: This manual is not public. Send an API token of its brand as a Bearer token in the Authorization header. Or a token came and it is not one of ours, or it has been revoked: This API token is not valid. A token is checked whenever one is sent, so a bad one is refused even on a public manual. Both answers carry WWW-Authenticate: Bearer. See Authentication.

403 Forbidden

This API token belongs to another brand. The token is valid but was made in a different brand. Make one in the brand that owns the manual.

404 Not Found

No published manual at this address. The slug is wrong, or the manual is not published. A path that is not one of the three answers Ask for {slug}.json, {slug}.pdf, or {slug}/tokens.json. An unpublished manual is a 404 rather than a 401 on purpose: the API does not say whether a manual exists until it is published.

410 Gone

This manual is no longer available. The manual had an end date and it has passed. The page says the same.

429 Too Many Requests

Too many requests. Up to N a minute. The allowance for this minute is used up. Wait for the seconds in Retry-After. The PDF address has a second, smaller allowance for renders, refused with Too many PDF renders. Up to N a minute. See Rate limits.

503 Service Unavailable

On the PDF address only. PDF export is not available on this server. or The PDF could not be rendered. Try again in a moment. See PDF.

What to do about each

401 and 403 are configuration. Fail loudly, fix the token, do not retry.
404 is the address. Check the slug against the dashboard, under API (opens in a new tab), which prints the exact one.
410 is final until somebody changes the end date in the manual's settings.
429 is worth a retry after the seconds in Retry-After. 503 is worth one after a moment; it names no wait.

PreviousCaching and CORS NextComplete examples

Something the API does that this page does not say? Write to hello@stylehub.cloud with the request and the answer you got.