Error format: The UIID API uses standard HTTP status codes, and every error payload includes a status field and an error key describing what went wrong.
The codes you'll see: 400 Invalid Request, 401 Unauthorized, 403 Forbidden (this one also includes a required_scope field telling you exactly which permission scope was missing), and 404 Not Found (returned as JSON, not an HTML error page).
Rate limiting: Each token is limited to 100 requests per 60 seconds. Design your integration to cache what you can and avoid unnecessary polling.
Pagination: List endpoints use cursor-based pagination via a next_cursor field rather than page numbers, so keep following the cursor until it's no longer returned.
Avoiding the rate limit with webhooks: If you find yourself polling an endpoint repeatedly to detect changes, subscribe to a webhook instead via POST /api/v1/webhooks (for example for alias.data.created or alias.data.updated events). Every webhook call includes an X-UIID-Signature header so you can verify it with HMAC-SHA256 using the secret you received at subscription time.
Debugging a 403 quickly: Check the required_scope in the error response against the Permission Scopes table (for example core:write requires MFA, storage:immutable requires 2FA) and request that scope during the OAuth authorize step.