Pagination
Collection endpoints generally accept limit plus a cursor such as before or after. Treat cursors as opaque identifiers, preserve server order, stop when the returned page contains fewer items than requested, and de-duplicate resource IDs when data can change during traversal. Consult the interactive operation schema because not every collection supports the same direction.
GET /api/v1/channels/<channel_id>/messages?limit=50&before=<message_id>
Authorization: Bot <token>Errors, retries and rate limits
Errors use { error: { code, message } }. Preserve the HTTP status, error code and X-Request-ID in logs. Retry network failures, 429 and selected 5xx responses only when the operation is idempotent or uses an application-level idempotency key.
| Response | Client action |
|---|---|
| 400 / 422 | Fix input; do not retry automatically |
| 401 | Refresh a human session or rotate invalid credentials |
| 403 | Review membership, role and channel permissions |
| 404 | Treat as absent; some private resources are intentionally hidden |
| 409 | Reload current state before deciding whether to retry |
| 429 | Wait for Retry-After, then add jitter |
| 5xx | Use bounded exponential backoff and surface persistent failure |
Versions and compatibility
The stable REST prefix is /api/v1. During beta, additive response fields, new enum values and new Gateway events may appear without a version change. Clients must ignore unknown fields and events. Removing fields, changing meaning or tightening accepted input requires a documented migration and a new API version or an announced compatibility window.
OpenAPI is the machine contract
Pin the downloaded contract in generated-client builds and review its diff during upgrades. The portal CI rejects route-table drift, but consumers still decide when to adopt a newer contract.
Deprecations and migrations
- Deprecated operations remain documented with their replacement and removal window
- Security removals may happen faster when continued support creates material risk
- SDK changelogs follow semantic versioning and identify breaking migrations
- Test against a staging node before changing production credentials or Gateway intents
Security checklist
- Keep Bot and webhook tokens in a secrets manager
- Use HTTPS and WSS outside localhost
- Never send a Bot Authorization header to a webhook-token URL
- Validate interaction and callback identifiers before acting
- Redact tokens, message content and personal data from diagnostics
- Rotate credentials after any suspected exposure and verify that the old token is rejected