Error Handling

Error responses

When a request fails, the API returns a JSON error object with a code and human-readable message. Always check the HTTP status code first, then parse the error body for details.

{
  "error": {
    "code": "error_code",
    "message": "A description of what went wrong"
  }
}

Credit management

Each address validation consumes one credit. When credits are exhausted, the API returns 402 Payment Required with your current balance:

{
  "error": {
    "code": "insufficient_credits",
    "message": "No address credits remaining",
    "credits_remaining": 0,
    "credits_limit": 50
  }
}

The credits_remaining and credits_limit fields let you track usage programmatically — for example, to alert your team before credits run out or to pause processing until more are purchased.

Invalid input (422)

Returned when the request body is missing or invalid:

{
  "error": {
    "code": "validation_failed",
    "message": "Original input can't be blank"
  }
}

Unauthorized (401)

Returned when the Authorization header is missing or the token is invalid. Double-check that your token is correct and hasn't been revoked.

Not found (404)

Returned when the account ID or address ID doesn't exist, or when you don't have access to the specified account.

Working with multiple accounts

If you belong to multiple accounts (personal and team), each has its own credit balance and address history. List your accounts to find the right one:

curl -H "Authorization: Bearer your_api_token" \
  https://addresspenny.com/api/v1/accounts

Use your team account for shared work, or your personal account for individual use. The account ID in the URL determines which credit balance is charged.