Reference
View as Markdown
Errors and limits
Every error has the same shape and is never charged. Anything that isn't a normal answer means not verified: don't trade on it.
The shape
{ "error": { "code": "RATE_LIMITED", "message": "Too many checks: …", "request_id": "01a1…", "details": { … } } }
message is written for a person; code is what your code should read. Quote the request_id when you write to us.
The errors
| Status | Code | What happened, and what to do |
|---|---|---|
| 400 | INVALID_JSON, INVALID_REQUEST | The body isn't JSON, or a field is missing or wrong. Fix the request; details lists what is wrong. |
| 400 | INVALID_ADDRESS | Not 0x and 40 hex characters, or its mixed case doesn't match its checksum (a typo). |
| 401 | INVALID_API_KEY | The key is wrong, revoked, or for the other service (a test key on api.lorglabs.com). |
| 402 | PAYMENT_REQUIRED | No payment, or one that didn't verify. The PAYMENT-REQUIRED header says what to pay: pay per check. |
| 402 | SETTLEMENT_FAILED | The payment verified but couldn't be settled. Nothing was taken; try again. |
| 404 | NOT_FOUND | No such endpoint. |
| 409 | IDEMPOTENCY_IN_PROGRESS | The first request with this Idempotency-Key is still running. Wait Retry-After. |
| 413 | PAYLOAD_TOO_LARGE | The body is over 2 KB. |
| 422 | UNSUPPORTED_CHAIN | A chain we don't cover yet. details lists the ones we do. |
| 422 | NOT_A_CONTRACT | A wallet sent to the token check. Use the address check. |
| 422 | IDEMPOTENCY_KEY_REUSED | The same Idempotency-Key with a different request. Use a new key. |
| 429 | RATE_LIMITED | Over a limit (below). Wait Retry-After seconds. |
| 500 | INTERNAL_ERROR | Our fault. Try again; if it repeats, write to us with the request_id. |
| 502 | FACILITATOR_UNAVAILABLE | The payment service didn't answer. Nothing was taken; try again. |
| 503 | CHECKS_INCOMPLETE | The "unknown" answer: a check we need couldn't finish. Not verified; ask again after Retry-After. |
| 503 | UPSTREAM_UNAVAILABLE, SERVICE_MISCONFIGURED | The service can't answer right now. Try again later. |
Limits
| Who | Limit |
|---|---|
| A key of your own | 60 checks a minute and 5,000 a day to start, raised on request. Refusals by the minute's limit don't use up the day's. |
| No key (pay per check) | 30 requests a minute from one IP address (an IPv6 network counts as one), price questions and paid checks together. |
| The public key | 10 checks a minute for each caller, and 1,000 a day shared by everyone. |
| Reports | A few a minute from one address; 500 a day for a key, 200 a day for everyone without one. |
Over a limit, the reply is 429 RATE_LIMITED with Retry-After in seconds. Nothing is charged and nothing is counted.