Errors and Retries

Understand Pullbay API error codes, HTTP status codes, and how to implement robust retry logic.

Error Response Format

All Pullbay API errors follow a consistent JSON envelope:

{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 400,
  "message": "Validation failed",
  "success": false,
  "error": { "code": "VALIDATION_ERROR" }
}

Field	Type	Description
requestId	string	Unique identifier for this request. Save this for debugging and support.
status	integer	HTTP status code mirrored in the body
message	string	Human-readable description of what went wrong
success	boolean	Always false for errors
error.code	string	Machine-readable error code for programmatic handling

The requestId is also returned as the X-Request-Id response header.

Always include requestId when contacting Pullbay support — it allows the support team to instantly locate your request in the logs.

---

HTTP Status Codes Reference

Status	Name	Retryable?	Meaning	What to Do
200	OK	N/A	Request successful	Process the response data
400	Bad Request	No	Invalid parameters or format	Fix your request and resubmit
401	Unauthorized	No	Invalid or missing API key	Verify your API key
402	Payment Required	No	Insufficient credits	Add credits in your dashboard
403	Forbidden	No	API key lacks permission	Use a key with the right permissions
404	Not Found	No	Endpoint or resource not found	Check the endpoint URL
429	Too Many Requests	Yes	Rate limit exceeded	Back off and wait for reset
500	Internal Server Error	Yes	Temporary server error	Wait and retry with backoff
502	Bad Gateway	Yes	Upstream service unavailable	Wait and retry
503	Service Unavailable	Yes	Maintenance or overload	Wait longer before retrying

---

Non-Retryable Errors (4xx except 429)

Do not retry requests that return 400, 401, 402, 403, or 404. These indicate problems with your request that won't resolve by waiting:

NON_RETRYABLE_CODES = {400, 401, 402, 403, 404}

if response.status_code in NON_RETRYABLE_CODES:
    body = response.json()
    print(f"Non-retryable error: {body['error']['code']}")
    print(f"Message: {body['message']}")
    print(f"Request ID: {body['requestId']}")
    # Fix the underlying issue; don't retry

Retryable Errors (429 and 5xx)

These errors are usually temporary and will likely succeed if retried with backoff:

RETRYABLE_CODES = {429, 500, 502, 503}

if response.status_code in RETRYABLE_CODES:
    print(f"Transient error {response.status_code} — implement backoff and retry")

---

Common Error Codes

Authentication Errors

Code	HTTP Status	Description	Solution
INVALID_API_KEY	401	API key is malformed or doesn't exist	Check your API key format and value
MISSING_API_KEY	401	Authorization header is missing	Include Authorization: Bearer <key>

Correct format:

headers = {
    "Authorization": "Bearer your_api_key_here"
}
# NOT: "Authorization": your_api_key_here"   (missing "Bearer ")
# NOT: "x-api-key: your_api_key_here"       (also accepted, but Bearer preferred)

Request Parameter Errors

Code	HTTP Status	Description	Solution
VALIDATION_ERROR	400	Parameter has invalid value or wrong type	Check parameter types and constraints

Example:

{
  "requestId": "3b8dcb68-...",
  "status": 400,
  "message": "Validation failed",
  "success": false,
  "error": { "code": "VALIDATION_ERROR" }
}

Fix — include all required parameters with correct types:

# Missing required parameter
params = {"maxItems": 50}  # Missing 'location'!

# Correct
params = {
    "location": "Seattle, WA",  # Required
    "maxItems": 50              # Optional
}

Credit Errors

Code	HTTP Status	Description	Solution
INSUFFICIENT_CREDITS	402	Account has run out of API credits	Add credits via dashboard or upgrade plan

Example:

{
  "requestId": "3b8dcb68-...",
  "status": 402,
  "message": "Insufficient credits",
  "success": false,
  "error": { "code": "INSUFFICIENT_CREDITS" }
}

Do not retry a 402 — user action is required (top up credits):

if response.status_code == 402:
    body = response.json()
    print(f"Out of credits. Request ID: {body['requestId']}")
    print("Visit your Pullbay dashboard to add credits.")
    # Do not retry

Rate Limit Errors

Code	HTTP Status	Description	Solution
RATE_LIMIT_EXCEEDED	429	Per-second or per-minute rate limit hit	Back off and retry after the reset window

Rate limits are enforced per API key on both a per-second and a per-minute basis based on your plan. The response headers indicate the current limit state:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712973600

Handle a 429:

if response.status_code == 429:
    reset_timestamp = int(response.headers.get("X-RateLimit-Reset", 0))
    wait_seconds = max(reset_timestamp - time.time(), 1)
    print(f"Rate limited. Waiting {wait_seconds:.1f}s...")
    time.sleep(wait_seconds + 1)
    # Then retry

Server Errors

Code	HTTP Status	Description	Solution
—	500	Unexpected server error	Retry with exponential backoff
—	502	Upstream service unavailable	Retry with backoff
—	503	Service maintenance or overload	Wait longer before retrying

---

Retryable vs. Non-Retryable Summary

Error Type	Status Codes	Retry?
Authentication	401	No — fix your key
Bad request	400	No — fix your parameters
Insufficient credits	402	No — add credits
Forbidden	403	No — check permissions
Not found	404	No — check endpoint URL
Rate limited	429	Yes — wait for reset
Server errors	500, 502, 503	Yes — exponential backoff
Network timeout	—	Yes — retry with backoff

---

Production-Ready Python Retry Implementation

import time
import random
import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://api.pullbay.com"

RETRYABLE_CODES = {429, 500, 502, 503}
NON_RETRYABLE_CODES = {400, 401, 402, 403, 404}


class PullbayClient:
    def __init__(self, api_key, max_retries=5, base_delay=1):
        self.api_key = api_key
        self.max_retries = max_retries
        self.base_delay = base_delay

    def get(self, endpoint, params=None):
        headers = {
            "Authorization": f"Bearer {self.api_key}",
        }

        for attempt in range(self.max_retries + 1):
            try:
                response = requests.get(
                    f"{BASE_URL}{endpoint}",
                    params=params,
                    headers=headers,
                    timeout=30,
                )

                if response.status_code == 200:
                    return response.json()

                elif response.status_code in NON_RETRYABLE_CODES:
                    body = response.json()
                    raise Exception(
                        f"Non-retryable error {response.status_code}: "
                        f"{body['error']['code']} — {body['message']} "
                        f"(requestId: {body['requestId']})"
                    )

                elif response.status_code in RETRYABLE_CODES:
                    if attempt < self.max_retries:
                        wait = self._backoff(attempt, response)
                        print(
                            f"Retryable error {response.status_code} "
                            f"on attempt {attempt + 1}. "
                            f"Waiting {wait:.1f}s..."
                        )
                        time.sleep(wait)
                    else:
                        body = response.json()
                        raise Exception(
                            f"Max retries ({self.max_retries}) exceeded. "
                            f"Last error: {response.status_code} — {body['message']}"
                        )

            except requests.Timeout:
                if attempt < self.max_retries:
                    wait = self._backoff(attempt, None)
                    print(f"Timeout on attempt {attempt + 1}. Waiting {wait:.1f}s...")
                    time.sleep(wait)
                else:
                    raise Exception("Max retries exceeded: Timeout")

            except requests.ConnectionError as e:
                if attempt < self.max_retries:
                    wait = self._backoff(attempt, None)
                    print(f"Connection error on attempt {attempt + 1}: {e}. Waiting {wait:.1f}s...")
                    time.sleep(wait)
                else:
                    raise

        raise Exception("All retry attempts exhausted")

    def _backoff(self, attempt, response):
        if response and response.status_code == 429:
            reset = int(response.headers.get("X-RateLimit-Reset", 0))
            if reset > 0:
                return max(reset - time.time(), 1) + 1  # +1s buffer

        # Exponential backoff with 10% jitter
        delay = (2 ** attempt) * self.base_delay
        jitter = random.uniform(0, delay * 0.1)
        return delay + jitter


# Usage

client = PullbayClient(api_key=API_KEY, max_retries=5)

try:
    result = client.get(
        "/apartments/properties",
        params={"location": "Seattle, WA", "maxItems": 50}
    )
    data = result["data"]
    credits_charged = result["pricing"]["creditsCharged"]
    request_id = result["requestId"]
    print(f"Got {len(data)} results. Credits charged: {credits_charged}. Request ID: {request_id}")
except Exception as e:
    print(f"Failed: {e}")

---

Debugging Tips

1

Always log the requestId

Every response includes a requestId. Log it alongside every API call so you can reference it when contacting support.

result = client.get("/apartments/properties", params={"location": "Seattle, WA"})
print(f"Request ID: {result['requestId']}")  # Save this in your logs

2

Verify your parameters

Common mistakes:

• Missing required parameters

• Wrong types (e.g. string instead of integer)

• Values outside valid ranges (e.g. maxItems exceeding the endpoint limit)

• Mutually exclusive parameters used together (e.g. page and maxItems)

3

Check your API key

• Copy-paste directly from your Pullbay dashboard

• Include the Bearer prefix in the header

• Check that the key has not been revoked

# Correct
headers = {"Authorization": "Bearer your_api_key_here"}

# Wrong — missing "Bearer "
headers = {"Authorization": "your_api_key_here"}

4

Monitor rate limits

Check rate-limit headers on every response to proactively throttle:

response = requests.get(f"{BASE_URL}/apartments/properties", headers=headers)
remaining = response.headers.get("X-RateLimit-Remaining")
limit = response.headers.get("X-RateLimit-Limit")
reset = response.headers.get("X-RateLimit-Reset")
print(f"Rate limit: {remaining}/{limit}, resets at {reset}")

5

Check account credit balance

A 402 means your balance is zero. Add credits in the Pullbay dashboard and do not retry the same request programmatically.

6

For 5xx errors, retry with backoff

500, 502, and 503 are temporary. The recommended strategy is exponential backoff with jitter (see the implementation above).

Frequently Asked Questions

Are credits charged for failed requests?

• 429 (rate limit) — credits are not charged.

• 4xx parameter errors — credits are not charged.

• 5xx transient errors — credits are generally not charged, but check pricing.creditsCharged in the response to confirm.

• Successful requests (200) — credits are charged as shown in pricing.creditsCharged.

What does VALIDATION_ERROR mean?

It means one or more query parameters failed validation — missing a required field, a value outside the allowed range, or mutually exclusive parameters used together. Check the message field and compare your request against the endpoint's parameter table.

How do I handle rate limits gracefully?

Read the X-RateLimit-Reset header and wait until that Unix timestamp before retrying. The Python example above handles this automatically.

Can I increase retry attempts?

Yes — pass a higher max_retries to the client constructor. However, be aware that aggressive retrying during a sustained outage can look like a DDoS. For sustained failures, implement a circuit breaker that stops retrying after a threshold and alerts your on-call team.

What is X-Request-Id?

It is the same value as requestId in the response body, returned as a response header. Use whichever is more convenient for your logging layer.