Brand API errors, paging and rate limitsBeta
The error codes, how to page through brand lists with a cursor and the limit of 120 requests a minute per token.
This page explains what the Brand API returns when a call fails, how list calls page through results, and how many requests a token can make. To make these calls, you need a Brand API token. Create a token on the Developers page, then follow the Brand API quick start for the first calls.
Responses
Requests and responses are JSON, except brand.md, which comes back as text/markdown. Responses from the Brand API routes carry an X-Tarkle-Api-Version: v1 header, so your code can check which version answered. They are sent with Cache-Control: no-store, so a response is not cached.
Errors
Every error has the same shape: { "error": { "code": "...", "message": "..." } }. The code names the kind of error, and the message says what went wrong.
Status | Code | Meaning |
|---|---|---|
400 |
| A parameter or body field has the wrong value or type, or a brand update has no valid field to change. |
401 |
| The token is missing, wrong or revoked. |
403 |
| The token does not have the scope the call needs, or the workspace is closed or deleted. |
404 |
| No such brand or request in the token's workspace. |
409 |
| The request was already approved or rejected, and the call repeats that decision. |
429 |
| The token made more than 120 requests in a minute. See Rate limit below. |
500 |
| Something went wrong on Tarkle's side. Retry later. |
A 400 can also come from a brand in the address that is neither an id nor a slug, a limit or cursor that is not valid, a request status other than pending, approved or rejected, a decision body that is not "approve" or "reject", or a request id in the wrong format. A brand update returns 400 when it has a field of the wrong type, an empty name, or restricted access on a brand with no contact or organization assigned. The update a brand through the API article lists the fields a brand update can change. Text longer than a field allows is cut to that field's maximum length and is not rejected.
A 404 message reads Brand not found or Request not found. A 409 message reads This request is already approved. or This request is already rejected. To approve or reject a request, see Manage access requests through the API.
Paging
The brands list (GET /brands) and the requests list of a brand (GET /brands/{brand}/requests) return one page at a time. Both take limit and cursor. limit is a whole number from 1 to 100, and it is 25 when you leave it out. A limit outside that range, or one that is not a whole number, returns 400 with the message limit must be a whole number from 1 to 100. Tarkle does not round it to the nearest valid value.
Each page returns next_cursor. Send it back as cursor to get the next page. A malformed cursor returns 400 with the message Invalid cursor, and so does a cursor that starts past the first 1,000,000 results.
A full page always returns a next_cursor, even when no results are left. When the total is an exact multiple of limit, the next call returns an empty list with next_cursor set to null. Stop only when next_cursor is null, because a list whose length is a multiple of limit ends with an empty page.
The requests list also takes status, which can be pending, approved or rejected. Any other value returns 400. For each call and the fields it returns, see Brand API endpoints.
Rate limit
Each token can make 120 requests a minute. Only requests with a valid token count, and a request that returns 403 for a missing scope counts too, because the limit is checked before the scope.
The X-RateLimit-Limit header shows the limit, and X-RateLimit-Remaining shows how many requests are left. They come with successful responses and with 403 and 429 responses. A 401 response has neither header, because the limit applies only once the token is valid. There is no reset header.
When a token goes over 120 requests, the response is 429 with the message Too many requests. Try again in a minute. and a Retry-After header. That header is always 60. The window lasts 60 seconds from the first request counted in it, so the wait can be shorter than the header says, but waiting 60 seconds is always enough. If Tarkle cannot reach the service that counts requests, the requests are not limited and the headers are missing.
Your workspace only
A token only reaches the workspace it was created in. You never send a workspace id, because Tarkle takes the workspace from the token. A brand or request from another workspace returns the same 404 as one that does not exist.