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:
{
"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"
}codeis the kind of error, the field to match on in code:validation,unauthorized,forbidden,not-found,rate-limitedorserver-error.typeis the same kind as a URI.titleis a short summary of the kind, anddetail, when there is one, says what went wrong this time.instanceis the path you called.correlationIdidentifies the request. Quote it when you contact support: for a500it points to the exact entry in Blazot's logs.
Errors and what to do
| Error | What happened | What to do |
|---|---|---|
400validation |
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. |
401unauthorized |
The token is missing, expired or no longer valid, or the account can't use the API. See 401 Unauthorized. | Depends on the detail. |
403forbidden |
You asked for something your account can't have, for example includeHubTransmissions=true on someone else's timeline. |
Change the request. |
404not-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. |
429rate-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. |
500server-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 exactlyRetry-Afterseconds later can be refused again, withRetry-After: 0.X-RateLimit-Limit: the requests allowed in the window.X-RateLimit-Remaining: the requests left in it,0on a429.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.
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.