Get started

Errors

Every error has a stable code, an HTTP status and a link back to this page.

Error shape

REST calls return the status code and a JSON body.

REST

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry in 1 s.",
    "status": 429,
    "docs": "https://tide.ad/docs/errors#rate_limited"
  }
}

JSON-RPC calls return the error object in the body. The stable code is in error.data.code.

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32429,
    "message": "Too many requests. Retry in 1 s.",
    "data": { "code": "rate_limited", "docs": "https://tide.ad/docs/errors#rate_limited" }
  }
}

Match on code, not on the message. New codes may be added. A code never changes meaning. JSON-RPC also uses -32600 for an invalid request.

Codes

Code	HTTP	JSON-RPC
invalid_params	400	-32602
unauthorized	401	-32401
forbidden_origin	403	-32403
out_of_credits	402	-32402
rate_limited	429	-32429
not_found	404	-32004
not_indexed	404	-32004
not_implemented	501	-32601
upstream_busy	503	-32503
method_not_found	404	-32601
internal	500	-32000

invalid_params

HTTP 400. JSON-RPC -32602. A parameter is missing, has the wrong type or is out of range. The message names the parameter.

Check the parameters table on the method page and send the call again.

unauthorized

HTTP 401. JSON-RPC -32401. The key is missing where one is required, or it is not a valid key.

Send a valid key in x-api-key, in the api-key query parameter or as a bearer token. Check that the key was not revoked.

forbidden_origin

HTTP 403. JSON-RPC -32403. The call came from an origin or IP the key does not allow.

Add the origin or IP to the key's allowed list in the developer portal, or call from an allowed place.

out_of_credits

HTTP 402. JSON-RPC -32402. The key has used all of its credits for the month (keyless: for the day).

Wait for the reset, message @suidevv on Telegram (https://t.me/suidevv) to move to a paid plan, or use another key. Errors never cost credits.

rate_limited

HTTP 429. JSON-RPC -32429. Too many requests a second for the key's plan and rate class.

Wait the number of seconds in the retry-after header, then retry with backoff. Batch where the method allows it.

not_found

HTTP 404. JSON-RPC -32004. The thing you asked for does not exist: an unknown digest, object, address history or name.

Check the id. New transactions can take about a second to appear.

not_indexed

HTTP 404. JSON-RPC -32004. The index does not cover the range you asked for yet. The error data holds the lowest checkpoint it can answer from.

Ask for a later range, or use the checkpoint in the error data as your lower bound.

not_implemented

HTTP 501. JSON-RPC -32601. The method exists in the registry but is not live yet.

It is on the roadmap. Check the method page for its phase.

upstream_busy

HTTP 503. JSON-RPC -32503. The service is shedding load. Keyless and Free calls are shed first.

Retry after a few seconds with backoff. A paid key is shed last.

method_not_found

HTTP 404. JSON-RPC -32601. No method or path has that name.

Check the spelling against the method list. Names are case sensitive.

internal

HTTP 500. JSON-RPC -32000. Something failed on our side.

Retry once. If it keeps failing, send us the x-request-id header of the response.