Errors

When a request fails, Encrata returns a standard HTTP status code and a JSON body describing what went wrong. This page lists every code and how to recover from the common ones.

Error format

Errors are JSON. The body shape depends on the endpoint family:

{
  "error": "Rate limit exceeded. Please try again later."
}

{
  "error": "rate limit exceeded"
}

Both families use the same error key. Standard endpoints return a full sentence; lookup endpoints return a short machine-readable phrase. Branch on the HTTP status code, not the message text.

Status codes

Code	Name	When
`200`	OK	Request succeeded
`201`	Created	Resource created (lists, webhooks, API keys)
`202`	Accepted	Bulk job queued
`204`	No Content	Delete succeeded
`400`	Bad Request	Invalid or missing request body or parameters
`401`	Unauthorized	Missing or invalid API key
`402`	Payment Required	Insufficient credits for the operation
`403`	Forbidden	Permission denied (wrong workspace role)
`404`	Not Found	Resource does not exist
`405`	Method Not Allowed	Wrong HTTP method
`409`	Conflict	Resource already exists (duplicate)
`413`	Payload Too Large	Request body exceeds the size limit (bulk)
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server failure
`502`	Bad Gateway	Upstream data provider failed
`503`	Service Unavailable	Required service not configured
`504`	Gateway Timeout	Upstream provider timed out

Handle common errors

401 Unauthorized

Your API key is missing, invalid, or revoked.

{"error": "unauthorized"}

Fix: Send an active key in the Authorization: Bearer <key> header. If the key was revoked, create a new one.

402 Payment Required

Your account does not have enough credits, or an API key has reached its credit limit.

{"error": "Insufficient credits"}

Fix: Add credits on the billing page, or raise the key’s credit limit. Repeat lookups of an address you already queried are free within the billing window.

403 Forbidden

Your credential is valid, but your workspace role does not permit this action.

{"error": "Insufficient permissions"}

Fix: Use a key with a non-readonly role, or ask a workspace admin.

429 Too Many Requests

You sent requests faster than the endpoint allows.

{"error": "Rate limit exceeded. Please try again later."}

The response carries headers to time your retry:

Header	Meaning
`Retry-After`	Seconds to wait before retrying. Use this.
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	When the window resets

Fix: Wait Retry-After seconds, then retry with exponential backoff. See Rate limits.

5xx Server and upstream errors

500 is an unexpected failure. 502, 503, and 504 mean an upstream data provider failed, is unconfigured, or timed out.

{"error": "upstream provider failed"}

Fix: These are usually transient. Retry with exponential backoff. You are not charged for a failed lookup.

Retry safely

Never retry a 400 or 401 unchanged. The request or credential is wrong, so the retry fails identically. Fix the cause first.

Retry with backoff	Fix first, do not retry
`429`, `500`, `502`, `503`, `504`	`400`, `401`, `403`, `404`, `405`, `409`, `413`

Prefer the Retry-After header, which is always the number of seconds to wait, over parsing X-RateLimit-Reset for retry timing.

Overview

Configuration

Best practices

Error format

Status codes

Handle common errors

Retry safely

Next steps

Rate limits

Create API key

​Error format

​Status codes

​Handle common errors

​Retry safely

​Next steps

Rate limits

Create API key

Error format

Status codes

Handle common errors

Retry safely

Next steps