Developers

On this page
Using the API

Errors

When a call fails, the API answers with an HTTP status and, almost always, a Problem Details body that says what went wrong. Match on its code, read its detail, and quote its correlationId if you contact support.

The error body

Errors use Problem Details (RFC 9457), with the content type application/problem+json:

JSON
{
  "type": "https://api.blazot.com/problems/not-found",
  "title": "Resource not found",
  "status": 404,
  "instance": "/v2/users/nobody",
  "correlationId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "code": "not-found"
}
  • code is the kind of error, the field to match on in code: validation, unauthorized, forbidden, not-found, rate-limited or server-error. type is the same kind as a URI.
  • title is a short summary of the kind, and detail, when there is one, says what went wrong this time.
  • instance is the path you called.
  • correlationId identifies the request. Quote it when you contact support: for a 500 it points to the exact entry in Blazot's logs.

Errors and what to do

Error What happened What to do
400
validation
A parameter's value isn't valid: a bad cursor or hashtag, or a value of the wrong type. The detail says what's wrong; a value of the wrong type is named with its parameter, for example take: The value 'abc' is not valid. Fix the request. Sending it again won't help.
401
unauthorized
The token is missing, expired or no longer valid, or the account can't use the API. See 401 Unauthorized. Depends on the detail.
403
forbidden
You asked for something your account can't have, for example includeHubTransmissions=true on someone else's timeline. Change the request.
404
not-found
It doesn't exist, or your account can't see it, for example a private hub you aren't a member of or an account that isn't available. The API doesn't say which. Check the name or id. If it's right, your account can't see it.
429
rate-limited
You've used up your read budget for the current window, or the token limit. See 429 Too Many Requests. Wait Retry-After seconds, plus one.
500
server-error
Something went wrong at Blazot, such as a brief outage while it looks up your key. Try again later. If it keeps happening, contact support with the correlationId.

401 Unauthorized

The detail tells you what to do:

detail What it means What to do
The access token is missing, invalid or expired. Get one from /v2/auth/token. There's no Authorization: Bearer header, or the token has expired or isn't a valid token. Get a new token and retry once.
Invalid access token. The token was valid, but its key has since been regenerated, or the account has been deleted for good. Get a new token with the current key and secret.
Account is unavailable. The account can't use the API right now: it's disabled, suspended or scheduled for deletion, or its subscription payment is past due. For a Site's key, the same applies when the Site's own subscription or its owner's is past due, or the owner is unavailable. Fix the account on Blazot. A new token won't help.

The first two also carry a WWW-Authenticate: Bearer header, so a client can renew its token whenever it sees one. Account is unavailable. has none, because a new token wouldn't help.

The token call itself fails with its own two messages, Invalid API credentials. and Account is unavailable.: see Authentication.

429 Too Many Requests

A 429 comes with headers that say where you stand:

  • Retry-After: seconds until the window's last second. Wait one second more: the window's last second still belongs to it, so a call made exactly Retry-After seconds later can be refused again, with Retry-After: 0.
  • X-RateLimit-Limit: the requests allowed in the window.
  • X-RateLimit-Remaining: the requests left in it, 0 on a 429.
  • X-RateLimit-Reset: the window's last second, as a Unix time in seconds. Calls work again from the second after it.

These headers are sent only on a 429, not on successful calls. Rate limits has the budget for each subscription level and how the window works.

The token call has its own limit, 3 requests per 5 minutes, and its own 429, whose detail asks you to reuse your token: see Authentication.

Important

A 429 right after a run of 401s usually means a stale token, not a spent budget. When a token is still unexpired but its key has been regenerated, or its account is disabled, deleted or suspended, the API can't count your reads against the account, so it counts them by IP address instead: 3 requests per 15 minutes. Once those are used, the 401s turn into 429s. Get a new token instead of waiting, and if the token call fails, its error says why. (A missing or expired token costs nothing at all, and a past-due account's 401s count against its own budget.) Rarely, a brief problem at Blazot can also put a call in the IP-address count.

Responses without a body

A few mistakes are answered before the API reaches the code that writes Problem Details, so they come back with an empty body:

Status When What to do
400 The path names a version other than 2, such as /v3/meta. Use /v2/: the api-supported-versions header lists the versions a path can name (today 2.0).
404 The path matches no endpoint: a typo, or an id in the wrong format (a transmission id that isn't a GUID). Check the path against the API reference.
405 You used a method the path doesn't take, such as a POST to a read. Use GET: every endpoint in the reference is a GET.

Contacting support

Quote the correlationId, the time of the call (with its time zone) and the endpoint: Support says where to write and what else to include. Never send your key, secret or token.