API errors

Every error the v2 API can answer, by code. Each error body links to its entry here.

Error shape#

Errors share one body. Branch on code, which never changes meaning; message is for people and may be reworded. param names the parameter at fault, when there is one.

429 rate_limited
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests this minute.",
    "docUrl": "https://polywhaler.com/docs/api/v2/errors#rate_limited",
    "requestId": "req_7d0c8e1f2a3b4c5d6e7f8091a2b3c4d5"
  }
}
  • The HTTP status always follows from the code: a not_found is always a 404.
  • Server errors never carry internal detail. Quote the requestId (also in the X-Request-Id header) when you write to us and we can find the request.
  • The API reference lists the errors each endpoint can answer.

Request errors#

type: "invalid_request_error"

invalid_param#

HTTP 400A parameter is invalid.

Do not retry unchanged: fix the request first.

unknown_param#

HTTP 400Unknown parameter.

Do not retry unchanged: fix the request first.

invalid_cursor#

HTTP 400The cursor is invalid, expired, or does not match the current filters.

Do not retry unchanged: fix the request first.

invalid_json#

HTTP 400The request body is not valid JSON.

Do not retry unchanged: fix the request first.

url_not_allowed#

HTTP 400The URL must be a public https endpoint on port 443 or 8443, without credentials, whose host does not resolve to a private address.

Do not retry unchanged: fix the request first.

filter_not_applicable#

HTTP 400A filter does not apply to any of the subscribed event types.

Do not retry unchanged: fix the request first.

not_found#

HTTP 404The resource does not exist.

Do not retry unchanged: fix the request first.

wallet_not_tracked#

HTTP 404This wallet has no whale trades and is not on the leaderboard.

Do not retry unchanged: fix the request first.

route_not_found#

HTTP 404No endpoint at this path.

Do not retry unchanged: fix the request first.

method_not_allowed#

HTTP 405This endpoint does not support the request method.

Do not retry unchanged: fix the request first.

idempotency_key_reused#

HTTP 409This Idempotency-Key was used with a different request.

Do not retry unchanged: fix the request first.

idempotency_in_progress#

HTTP 409A request with this Idempotency-Key is still being processed. Retry shortly.

Retry shortly with the same Idempotency-Key.

resource_limit_reached#

HTTP 409The account has reached the limit for this resource.

Do not retry unchanged: fix the request first.

conflict#

HTTP 409The resource is not in a state that allows this.

Do not retry unchanged: fix the request first.

gone#

HTTP 410This resource is no longer available.

Do not retry unchanged: fix the request first.

payload_too_large#

HTTP 413The request body is larger than 64 KB.

Do not retry unchanged: fix the request first.

unsupported_media_type#

HTTP 415Send the request body as Content-Type: application/json.

Do not retry unchanged: fix the request first.

Authentication errors#

type: "authentication_error"

missing_api_key#

HTTP 401Send your API key as Authorization: Bearer pwhk_....

Do not retry unchanged: fix the request first.

invalid_api_key#

HTTP 401The API key is not recognized.

Do not retry unchanged: fix the request first.

api_key_revoked#

HTTP 401This API key has been revoked.

Do not retry unchanged: fix the request first.

api_key_expired#

HTTP 401This API key has expired.

Do not retry unchanged: fix the request first.

Permission errors#

type: "permission_error"

plan_required#

HTTP 403API access requires an active Quant subscription.

Do not retry unchanged: fix the request first.

insufficient_scope#

HTTP 403This API key does not have the scope this endpoint requires.

Do not retry unchanged: fix the request first.

Rate limit errors#

type: "rate_limit_error"

rate_limited#

HTTP 429Too many requests this minute. Retry after the time in Retry-After.

Retry after the Retry-After header's seconds.

quota_exceeded#

HTTP 429The daily request quota is used up. It resets at 00:00 UTC.

Retry after the Retry-After header's seconds.

Server errors#

type: "api_error"

internal_error#

HTTP 500Internal error.

Retry with backoff; quote the requestId if it persists.

upstream_error#

HTTP 502An upstream service did not answer. Retry shortly.

Retry with backoff; quote the requestId if it persists.

temporarily_unavailable#

HTTP 503The service is temporarily unavailable. Retry shortly.

Retry with backoff; quote the requestId if it persists.