API
Handle API errors, limits and retries
Build reliable Premely API clients with clear error handling, safe retries and bounded pagination.
What it is
Premely uses standard HTTP status codes, application/problem+json error bodies, request IDs, rate-limit headers and idempotency controls.
Why use it
Use this guide to distinguish a request problem from an authentication, permission, conflict, rate-limit or service issue.
Before you start
- Log the safe
X-Request-Id, status and problem title. Never log the bearer token or full request payload by default.
How to use it
- 1
Check the HTTP status
Handle success, client errors, rate limits and temporary service errors separately.
- 2
Read the problem body
Use
status,title, optionaldetailandrequest_idto diagnose the request without exposing internal errors. - 3
Retry only when safe
Respect
Retry-After. Reuse a UUIDv7 idempotency key only when retrying the exact same write request. - 4
Escalate with the request ID
If support is needed, share the request ID and timestamp. Never share the API token.
Problem response
{
"type": "https://premely.io/problems/422",
"title": "Unprocessable request",
"status": 422,
"detail": "The selected metric and filter combination is not supported.",
"request_id": "0198f8f0-1234-7abc-8def-0123456789ab"
}HTTP status codes
| Status | Meaning | Client action |
|---|---|---|
400 | Malformed parameter or request shape. | Correct the request before retrying. |
401 | Missing, malformed, expired or revoked token. | Use a valid token. Do not retry repeatedly with the same credential. |
403 | The token lacks a required scope or allowed site. | Grant only the required scope or choose an authorized site. |
404 | The workspace-scoped resource was not found. | Check the identifier and token workspace. |
409 | Idempotency, resource state or immutable-field conflict. | Read the response and do not change a request under a reused key. |
410 | The requested export download expired. | Create a new export if it is still needed. |
413 | Request or result boundary exceeded. | Reduce the request size or analytics range. |
415 | Unsupported media type. | Send JSON with Content-Type: application/json. |
422 | Valid JSON with an unsupported field or metric combination. | Change the request to a supported combination. |
429 | Per-minute or per-day token limit reached. | Wait for Retry-After, then retry with backoff. |
503 | A service or dependency boundary is temporarily unavailable. | Retry after the provided delay and keep writes idempotent. |
Request and retry limits
- A standard token starts with 60 requests per minute and 10,000 requests per day. The effective minute limit and remaining count are returned in rate-limit headers.
- List endpoints use cursor pagination with a maximum page size of 100. Cursors are opaque and bound to the route, workspace and token.
- Write operations reserve the UUIDv7 idempotency key against the method, path and body. Exact retries replay the stored outcome. A changed request conflicts.
- Export ranges are limited to 90 days. Analytics ranges are limited to 366 days.
- JSON request bodies are limited to 64 KiB. API responses fail closed above 2 MB, and analytics responses are limited to 1,100 rows.
What to expect
Errors remain safe
Problem responses do not reveal token state, another workspace, provider credentials or internal stack details.
Retries stay bounded
Use exponential backoff with jitter for 429 and temporary 503 responses, and stop after a reasonable attempt limit.