Developers
Conventions: pagination, errors, limits, idempotency, versions
How every v1 endpoint behaves: cursor pagination, problem+json errors and their codes, rate limits and headers, idempotency keys, API versions and deprecation.
Pagination and filtering
List endpoints return { "data": [...], "nextCursor": "…" | null }. Pass nextCursor back as cursor until it is null; cursors are opaque, so don’t build or parse them. limit is 1 to 500 (default 100). Lists have a stable order, so paging doesn’t repeat or skip rows unless the data changes between calls.
fields=id,emailkeeps only those properties of each item (unknown names are ignored).- List responses carry an
ETag. Send it back asIf-None-Matchand an unchanged list answers304 Not Modifiedwith no body (the call still counts against your limit). - Filters (
teamId,status,from,toand so on) are listed per endpoint in the reference. Nested objects are not expandable; related ids (teamId,employeeId) point at other endpoints.
Errors
Every failure is an RFC 9457 problem document with Content-Type: application/problem+json:
{
"type": "https://tiniun.com/docs/api-conventions#err-insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential doesn’t have the “status:read” scope",
"code": "INSUFFICIENT_SCOPE",
"requestId": "3f0b6c52-9d1e-4f3a-8a71-5b2f0d7c9e10",
"requiredScope": "status:read",
"statusCode": 403,
"message": "This credential doesn’t have the “status:read” scope"
}{
"type": "https://tiniun.com/docs/api-conventions#err-validation-failed",
"title": "Invalid request",
"status": 400,
"detail": "limit: Too big: expected number to be <=500",
"code": "VALIDATION_FAILED",
"requestId": "…",
"errors": [{ "path": "limit", "message": "Too big: expected number to be <=500" }]
}Branch on code (stable) and the HTTP status, never on detail (wording changes). statusCode and message repeat status and detail for clients written against the first version. New codes can appear; treat unknown ones by their status. Quote requestId when you contact support.
UNAUTHENTICATED HTTP 401
The credential is missing, invalid, expired or revoked.
INSUFFICIENT_SCOPE HTTP 403
The credential lacks the scope the route needs (see `requiredScope`).
IP_NOT_ALLOWED HTTP 403
The API key can only be used from certain networks and this address is not one of them.
FEATURE_NOT_ENABLED HTTP 403
The organization’s plan doesn’t include the feature behind this route.
FORBIDDEN HTTP 403
The credential may not see or do this.
NOT_FOUND HTTP 404
No such resource, or it is outside the credential’s reach.
VALIDATION_FAILED HTTP 400
A parameter or body field is invalid; `errors` lists each problem.
BAD_CURSOR HTTP 400
The cursor isn’t valid; start again without it.
BAD_RANGE HTTP 400
`to` is not after `from`.
RANGE_TOO_LONG HTTP 400
The period is longer than the route allows.
INVALID_VERSION HTTP 400
`Tiniun-Version` isn’t a date in YYYY-MM-DD form.
CONFLICT HTTP 409
The request conflicts with the current state of the resource.
UNPROCESSABLE HTTP 422
The request is well formed but can’t be carried out.
PAYLOAD_TOO_LARGE HTTP 413
The request body is bigger than the limit.
IDEMPOTENCY_IN_PROGRESS HTTP 409
Another request with the same `Idempotency-Key` is still running. Retry shortly.
IDEMPOTENCY_KEY_REUSED HTTP 422
The `Idempotency-Key` was used before with a different request body.
BAD_IDEMPOTENCY_KEY HTTP 400
Use 8–64 characters: letters, digits, `_ - . :`.
RATE_LIMITED HTTP 429
The credential used up its budget; wait `Retry-After` seconds.
ORIGIN_NOT_ALLOWED HTTP 403
A browser page on another site tried to call the MCP endpoint.
INTERNAL HTTP 500
An error on our side. Quote the `requestId` when contacting support.
Rate limits
Each credential (API key or OAuth grant) has a per-minute budget. A call spends its cost: 1 for most, more for heavy ones. There is also a short-burst allowance of 50 calls per second at the default limit (five times the average rate, at least 5), so a spike is smoothed rather than refused for the whole minute, and an organization-wide ceiling across all its credentials so many keys can’t multiply the allowance. Counters are per credential: you never see anything about other organizations’ or other keys’ use.
| Plan | Default calls per minute |
|---|---|
| starter | 120 |
| growth | 600 |
| enterprise | 3000 |
The platform team can set a different limit for an organization, and an admin can lower any single key below it (Settings → Integrations → API keys) but never raise it. GET /v1/me shows the limits that apply to the credential you used.
| Header | Meaning |
|---|---|
| RateLimit-Limit | Calls per minute for this credential |
| RateLimit-Remaining | Budget left in the current minute |
| RateLimit-Reset | Seconds until the budget refills |
| RateLimit-Policy | The policy as limit;w=window, for example 600;w=60 |
| Retry-After | On 429 only: seconds to wait before retrying |
| X-RateLimit-Limit, -Remaining, -Reset | The same values under the older, widely used names. Kept for existing clients; prefer the RateLimit-* names (IETF draft “RateLimit header fields for HTTP”). |
| Call | Cost |
|---|---|
| GET /v1/shifts | 2 |
| GET /v1/interactions | 2 |
| GET /v1/adherence/daily | 3 |
| GET /v1/forecast/staffing | 5 |
| GET /v1/advisor/summary | 10 |
| POST /v1/interactions | 5 |
| Everything else | 1 |
When you get 429 RATE_LIMITED, wait Retry-After seconds (add a little random jitter), then retry. A refused call spends nothing. Spread scheduled jobs out instead of starting them all on the minute, and prefer wider date ranges or larger pages over many small calls.
Idempotency
Send Idempotency-Key: <unique string, 8-64 characters> on any POST that writes (today, POST /v1/interactions) to make a retry safe even if you don’t know whether the first attempt arrived. Use a random UUID per logical operation and reuse it only for retries of that same operation.
- The first request runs and its response is stored for 24 hours with a fingerprint of the method, route and body (field order doesn’t matter).
- The same key and body again returns the stored response with
Idempotent-Replayed: trueand does not run again. - The same key with a different body or route is refused:
422 IDEMPOTENCY_KEY_REUSED. - The same key while the first request is still running:
409 IDEMPOTENCY_IN_PROGRESSwithRetry-After: 1. Concurrent duplicates never both run. - Failed requests (4xx or 5xx) are not stored, so you can fix the request and reuse the key.
- Keys are private to your organization.
curl https://tiniun.com/api/v1/interactions -H "Authorization: Bearer spk_…" \
-H "Idempotency-Key: 4b0c5a9e-7d1f-4d2b-9a6e-1c2d3e4f5a6b" \
-H "Content-Type: application/json" -d @batch.json
# the same command again returns the same body and "Idempotent-Replayed: true"Versions and deprecation
The URL stays /v1; behavior changes are dated. Send Tiniun-Version: YYYY-MM-DD to ask for the behavior of a release (a date between releases gets the newest release not after it). Without the header, an API key gets the version that was current when the key was created, so an integration never changes under you, and OAuth tokens get the latest. Every response says which version served it in Tiniun-Version, and GET /v1/me shows the latest. Versions are listed, newest first, at GET /api/v1/changelog and in the changelog. The current version is 2026-10-11.
Additive changes (new endpoints, new optional parameters, new response fields, new error codes) can happen in any version, so ignore fields you don’t know. When something is being retired, affected responses carry Deprecation (RFC 9745), Sunset (RFC 8594) and a Link: <…>; rel="deprecation" header at least six months ahead of removal, and it is announced in the changelog. Nothing is deprecated today.
Request IDs
Send X-Request-Id (8 to 80 characters: letters, digits, . _ : -) and it is echoed back and logged; otherwise one is generated. Error bodies carry it as requestId.
Usage reports
An admin sees calls, errors, throttled calls and estimated response times per day, area and key or application under Settings → Integrations → API usage (and GET /admin/api-usage?from=&to=, which needs a signed-in organization admin). Response times are estimated from buckets (25, 50, 100, 250, 500, 1000, 2500 ms), so “typical” and “slowest 5%” are upper bounds of a bucket. Figures are kept 90 days and only ever show your own organization.
See it with your own scenarios
A 30-minute walkthrough with our team, tailored to your operation.
Book a demo
