HTTP Response Code | Meaning | Action to take |
|---|---|---|
| Success | Process the response. |
| Redirection | Client (browser in this case) must flow redirect. |
| Bad request | Check your API key, OAuth2 token and request body. Do not retry request. The troubleshooting pages for each API also have tips for what to look for! |
| Invalid auth | Check your API key, OAuth2 token and request body. Do not retry request. The troubleshooting pages for each API also have tips for what to look for! |
| Resource not available | Check your API key and request URL - you may be using the wrong key or the resource may have been unshared with your application or deleted. |
| Request entity too large | Your |
| Rate limit exceeded | Try again after rate limit period expires. |
| Oasis API failure | Wait and retry request. If you see these regularly, reach out to [email protected] |
| Not implemented | Your client is attempting an unsupported request. Try an alternative request. Do not retry request. |
Rate Limiting
Requests to Oasis are rate-limited. Requests are limited to 500 requests per minute per API Key. These limits are not averages; rather, the allowed count of requests resets every minute.
Rate-limited requests contain these HTTP response headers:
- X-RateLimit-Reset: Unix timestamp when the rate limit counter will be reset.
- X-RateLimit-Limit: The total number of requests allowed in a time period.
- X-RateLimit-Remaining: Number of requests that can be made until the reset time.
- X-RateLimit-Bucket: Name of the rate-limit bucket for this request
Request:
HOST api.oasis.gd
GET /nft-collections/123
X-OASIS-KEY ABCD
Response headers:
Status: 200 OK
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1199
X-RateLimit-Reset: 1394506274
X-RateLimit-Bucket: abc123
In case the client hits a rate limit, an empty response with a 429 Too Many Requests status code is returned.
Request:
HOST api.oasis.gd
GET /nft-collections/123
X-OASIS-KEY ABCD
Response headers:
Status: 429 Too Many Requests
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1394506274
X-RateLimit-Bucket: abc123
Retrying requests after errors
When a request against the Oasis API fails, use a retry strategy with exponential backoff (i.e. wait 1 second after first error, then 2, then 4, etc.). If you are unable to receive a successful response after five retries, you may want to cease the sync and resume at a later time.