Early accessWe're onboarding teams in batches. The sandbox and docs are open to everyone. Request access →

Skip to content
APIserver.in
Docs menu

Docs

Errors & billing

Every error has a stable code, a plain-English meaning — and costs ₹0.

The billing rule

You are never charged when a request fails, times out or a source is down. Every error response has meta.charged: false and amount_inr: 0. When we fall back across sources and one answers, you are billed once.

Error envelope

json
{
  "success": false,
  "request_id": "as_req_01J9X2M4B7C1D8E5F2G6H3J9KA",
  "error": {
    "code": "PROVIDER_TIMEOUT",
    "type": "provider_error",
    "message": "The source did not answer in time. You were not charged.",
    "retryable": true,
    "docs_url": "/docs/errors#provider_timeout"
  },
  "meta": {
    "charged": false,
    "amount_inr": 0,
    "latency_ms": 731,
    "attempts": 2
  }
}

VALIDATION_FAILED also includes error.fields: a list of { path, message } pairs you can map straight onto your form.

VALIDATION_FAILED 400

Something in the request isn't in the right shape — usually an ID with a typo or a missing field.

Fix: Fix the fields listed in `error.fields` and send again. · Retryable: no · Type: invalid_request_error · Billed: ₹0

AUTH_INVALID_KEY 401

We couldn't find a valid API key on this request.

Fix: Copy a key from the dashboard and send it as a Bearer token. · Retryable: no · Type: authentication_error · Billed: ₹0

WALLET_INSUFFICIENT_BALANCE 402

Your wallet doesn't have enough for this call, so we didn't run it.

Fix: Top up any amount from ₹100 and retry. · Retryable: no · Type: billing_error · Billed: ₹0

AUTH_SCOPE_DENIED 403

The key is valid but doesn't have access to this API or mode.

Fix: Use a key with the right scope, or a test key in the sandbox. · Retryable: no · Type: authorization_error · Billed: ₹0

RECORD_NOT_FOUND 404

The source has no record for this ID.

Fix: Double-check the ID. In the sandbox, use one of the sample IDs. · Retryable: no · Type: not_found_error · Billed: ₹0

RATE_LIMITED 429

You sent requests faster than your key's limit.

Fix: Back off for the `Retry-After` seconds and retry. Retries are safe with an Idempotency-Key. · Retryable: yes · Type: rate_limit_error · Billed: ₹0

INTERNAL_ERROR 500

We hit an unexpected error.

Fix: Retry with the same Idempotency-Key. If it persists, send us the request_id. · Retryable: yes · Type: api_error · Billed: ₹0

PROVIDER_UNAVAILABLE 503

All upstream sources for this check were down, even after fallback.

Fix: Retry in a minute. You were not charged. · Retryable: yes · Type: provider_error · Billed: ₹0

PROVIDER_TIMEOUT 504

The upstream source took too long to answer.

Fix: Retry — most timeouts clear within seconds. You were not charged. · Retryable: yes · Type: provider_error · Billed: ₹0

Retries

Retry only when error.retryable is true. Use exponential backoff with jitter, honour Retry-After, and send an Idempotency-Key so a retry can never be billed twice.

Rate limit: 25 requests burst, refilling at 10/s per key. See Rate limits.