API ReferenceOverview

Errors & pagination

How the API reports errors, and how to page through lists.

#Errors

Errors use standard HTTP status codes and a consistent JSON body with a stable code you can branch on:

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "traffic_limit_gb must be a positive number.",
    "param": "traffic_limit_gb"
  }
}

Status	Code	Meaning
`400`	`invalid_request`	A parameter is missing or invalid — see `param`
`401`	`invalid_api_key`	The key is missing, malformed or revoked
`403`	`insufficient_scope`	The key doesn't have the scope this endpoint needs
`404`	`not_found`	The resource doesn't exist on your account
`409`	`conflict`	The request conflicts with current state (e.g. a duplicate username)
`429`	`rate_limited`	Over 600 requests a minute — wait until `X-RateLimit-Reset`
`500`	`internal_error`	Something went wrong on our side; safe to retry

#Pagination

List endpoints return a page of results and a cursor for the next one:

JSON

{
  "data": [{ "id": "su_8f2k1d", "username": "acme-scraper" }],
  "has_more": true,
  "next_cursor": "su_8f2k1d"
}

Pass next_cursor back as starting_after to get the next page:

Shell

curl "https://api.riftip.com/v1/sub-users?limit=50&starting_after=su_8f2k1d" \
  -H "Authorization: Bearer $RIFTIP_API_KEY"

Parameter	Default	Notes
`limit`	`25`	1–100
`starting_after`	—	The `next_cursor` from the previous page

#Idempotency

POST requests accept an Idempotency-Key header. Retrying with the same key within 24 hours returns the original result instead of acting twice — use it for anything you might retry after a timeout.