HTTP Response Code

Meaning

Action to take

200

Success

Process the response.

302

Redirection

Client (browser in this case) must flow redirect.

400

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!

401

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!

404

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.

413

Request entity too large

Your limit parameter may be over 10000; reduce accordingly.

429

Rate limit exceeded

Try again after rate limit period expires.

500, 502, 503

Oasis API failure

Wait and retry request. If you see these regularly, reach out to [email protected]

501

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.