FAQ
Frequently asked questions about using the API docs: authentication, keys, limits, errors, and integration patterns.
Base URL
/api/v1
Auth Header
X-API-Key
Rate Limit Window
60s
Webhooks
Supported
API Basics
What is the API base URL?
Use https://api.snsauctions.xyz/api/v1 as the base URL for all v1 REST API endpoints.
Do API responses follow a standard format?
Yes. Success responses include success=true, a data object, and a timestamp. Error responses include success=false, an error message/code, and a timestamp.
Which read endpoints are public?
Docs indicate GET /api/v1/auctions and GET /api/v1/auctions/:id are available without an API key, but with lower rate limits than authenticated requests.
Authentication & Keys
How do I authenticate requests?
Send your API key in the X-API-Key header. Write endpoints require authentication.
What key formats are used?
The docs show sk_live_... for production keys and sk_test_... for dev/test usage.
Can I create my first key without an existing key?
Yes. The docs describe a bootstrap flow where POST /api/v1/keys/create can create your first key without providing X-API-Key.
What key types are available?
Developer, Agent, and Read-Only key types are documented.
Rate Limits
How is rate limiting implemented?
The rate limiting guide states Redis-backed fixed 60-second buckets are used, with endpoint-specific limits.
What happens when I hit a limit?
You receive HTTP 429 with a RATE_LIMITED error and a retry delay in seconds in the error message.
Do authenticated requests get higher limits?
Yes. For example, GET /api/v1/auctions is documented as 100/min public and 1000/min authenticated.
Errors & Reliability
How should I handle API errors?
Check HTTP status first, then parse the JSON error payload and handle by type (401, 400, 404, 429, 500) as described in the error handling guide.
Should I retry failed requests?
Retry transient errors such as 429 and 5xx with backoff. Do not retry authentication failures until credentials are fixed.
What common error codes are documented?
UNAUTHORIZED (401), INVALID_REQUEST (400), NOT_FOUND (404), RATE_LIMITED (429), and INTERNAL_ERROR (500).
Webhooks & Integrations
Are webhook endpoints documented?
Yes. The docs include create, list, retrieve, update, and delete webhook endpoints under /api/v1/webhooks... routes.
What events can I subscribe to?
Examples include auction.created, auction.bid, auction.settled, and auction.cancelled.
Do webhooks require authentication?
Yes. Webhook requests in the docs include X-API-Key, which means they require an authenticated API key.
Getting Started
Where should I start if I am new to the API?
Start with Quick Start, then read Authentication, API Keys, API Overview, and Rate Limiting before implementing write operations.
What is the fastest path to making my first successful request?
Create an API key, send it in X-API-Key, call GET /api/v1/auctions, and verify the success=true response shape shown in the docs.
How should I store API keys safely?
Store keys in environment variables, never hardcode them in source files, and rotate/revoke keys regularly if exposure is suspected.
Still have questions?
Use these docs sections for deeper implementation details.
© 2026 SNSAuctions.xyz. Built on Solana.