Brand API errors, paging and rate limitsBeta
The error format, how to page through results and how many requests a token can make.
Beta. The Brand API is in beta. Fields can still be added to version 1, and any breaking change will ship as a new version (/api/v2) rather than change v1.
Responses
Requests and responses are JSON, except brand.md, which is text/markdown. Every response carries an X-Tarkle-Api-Version: v1 header and is not cached.
Errors
Every error has the same shape: { "error": { "code": "...", "message": "..." } }.
Status | Code | Meaning |
|---|---|---|
400 |
| A parameter or body field is missing, not allowed or too long. |
401 |
| The token is missing, wrong or revoked. |
403 |
| The token does not have the scope the endpoint needs, or the workspace is closed. |
404 |
| No such brand or request in your workspace. |
429 |
| The token made too many requests. Wait, then retry. |
500 |
| Something went wrong on Tarkle's side. Retry later. |
Paging
List endpoints accept limit, a whole number from 1 to 100 (25 by default), and cursor. The response includes next_cursor. Send it back as cursor to get the next page. When next_cursor is null you have reached the last page. A malformed cursor returns 400.
Rate limit
Each token can make 120 requests a minute. The response headers show X-RateLimit-Limit and X-RateLimit-Remaining. When you go over, the response is 429 with a Retry-After header that says how many seconds to wait.
Your workspace only
A token only ever reaches the workspace it was created in. You never send a workspace id, and a brand from another workspace behaves as if it does not exist.