Reference

Errors

Errors use standard HTTP status codes and an application/problem+json body (RFC 9457) with a stable code you can switch on.

Error format

typeA link to the code on this page.
titleShort, human-readable summary.
statusThe HTTP status, repeated in the body.
codeStable machine-readable code. Switch on this, not on title or detail.
detailWhat went wrong in this request, when there is more to say.
positionFor invalid_query: character offset of the problem in q.
request_idAlso in the X-Request-Id header. Quote it when you contact support.

400 invalid_query400

{
  "type": "https://yieldsniper.finance/developers/errors#invalid_query",
  "title": "Invalid query",
  "status": 400,
  "code": "invalid_query",
  "detail": "Unknown field \"yield.apy\".",
  "position": 0,
  "request_id": "req_5670f65858310f3c37f932e4"
}

TypeScript

const res = await fetch(url, { headers })
if (!res.ok) {
  const problem = await res.json()
  switch (problem.code) {
    case 'rate_limited':
      await sleep(Number(res.headers.get('Retry-After') ?? 1) * 1000)
      break
    case 'invalid_query':
      console.error(problem.detail, 'at', problem.position)
      break
    default:
      throw new Error(`${problem.code} (${problem.request_id})`)
  }
}

Codes

400invalid_requestInvalid request
A parameter or body field is missing, has the wrong type or is out of range.
Read detail; it names the field.
400invalid_queryInvalid query
The text query does not parse, or names an unknown field or operator.
position is the character offset of the problem in q.
401unauthenticatedUnauthenticated
No key, a malformed key or a revoked key.
Send Authorization: Bearer ys_live_… with an active key.
402subscription_requiredSubscription required
The account behind the key has no paid plan, or the plan has ended.
Renew the plan in Billing. Keys keep working once it is active.
403forbiddenForbidden
The key lacks the scope, or the resource belongs to another account.
Create a key with the scope the endpoint lists.
404not_foundNot found
No object with that id, or no screen or report on that date.
Check the id prefix and the date format (YYYY-MM-DD).
409limit_reachedLimit reached
The account already has the maximum number of keys (5), saved queries (50), watchlists (50) or watched wallets (10).
Delete one first.
429rate_limitedToo many requests
More than 60 requests in a minute or 5,000 in a day on this key.
Wait Retry-After seconds. Cache responses: data changes once a day.
500internalInternal error
Something failed on our side.
Retry with backoff. Send request_id to support if it persists.
503unavailableUnavailable
The dataset is not available right now, for example while a new screen is being built.
Retry after a few minutes.

New codes may be added within v1. Treat an unknown code by its HTTP status: 4xx means change the request, 5xx means retry later.