Error mapping

Precium API Error Reference

This document provides a comprehensive reference for all error codes, their causes, and recommended resolution steps.

‍

Error Response Format

All API errors follow a consistent JSON structure:

‍

JSON

{
  "__all__": {
    "message": "Descriptive error message",
    "code": "error_code"
  }
}

‍

Field-specific errors:

JSON

{
  "email": {
    "message": "Enter a valid email address",
    "code": "invalid"
  },
  "purchase.currency": {
    "message": "This field is required",
    "code": "required"
  }
}

‍

HTTP Status Codes

‍

Authentication Errors

invalid_token

‍

HTTP Status: 401

‍

Message: Invalid or expired authentication token

‍

Causes:

• API key is incorrect
• API key has been revoked
• Using sandbox key in production or vice versa

‍

Resolution:

1. Verify your API key in the dashboard
2. Ensure you're using the correct environment
3. Generate a new API key if necessary

‍

missing_authorization

‍

HTTP Status: 401

‍

Message: Authorization header is required

‍

Causes:

• No Authorization header provided
• Malformed Authorization header

‍

Resolution:

BASH

# Correct format
-H "Authorization: Bearer YOUR_API_KEY"

# Common mistakes
-H "Authorization: YOUR_API_KEY"  # Missing "Bearer"
-H "Bearer YOUR_API_KEY"          # Missing "Authorization:"

‍

Validation Errors

required

‍

HTTP Status: 400

‍

Message: This field is required

‍

Example:

JSON

{
  "brand_id": {
    "message": "This field is required",
    "code": "required"
  }
}

‍

Resolution: Include all required fields in your request.

‍

invalid

‍

HTTP Status: 400

‍

Message: Invalid value for this field

‍

Common Cases:

‍

invalid_uuid

‍

HTTP Status: 400

‍

Message: Invalid UUID format

‍

Causes:

• client_id or brand_id is not a valid UUID
• UUID contains invalid characters

‍

Valid UUID format:

3fa85f64-5717-4562-b3fc-2c963f66afa6

‍

max_length

‍

HTTP Status: 400

‍

Message: Ensure this field has no more than X characters

‍

Field Limits:

‍

min_value / max_value

‍

HTTP Status: 400

‍

Message: Ensure this value is greater/less than X

‍

Amount Limits:

‍

Purchase Errors

purchase_not_found

‍

HTTP Status: 404

‍

Message: Purchase not found

‍

Causes:

• Invalid purchase ID
• The purchase belongs to a different merchant
• Purchase has been deleted

‍

Resolution:

1. Verify the purchase ID is correct
2. Ensure you're using the correct API key

‍

purchase_already_paid

‍

HTTP Status: 409

‍

Message: Purchase has already been paid

‍

Causes:

• Attempting to charge an already-completed purchase
• Duplicate payment submission

‍

Resolution:

• Check purchase status before charging
• Implement idempotency in your integration

‍

purchase_cancelled

‍

HTTP Status: 409

‍

Message: Purchase has been cancelled

‍

Causes:

• Attempting to charge a cancelled purchase
• Purchase expired and was auto-cancelled

‍

Resolution:

• Create a new purchase for the transaction

‍

purchase_expired

‍

HTTP Status: 409

‍

Message: Purchase has expired

‍

Causes:

• due the date has passed with due_strict: true
• Direct post URL has expired (15-minute validity)

‍

Resolution:

• Create a new purchase
• Process payments promptly after creation

‍

invalid_amount

‍

HTTP Status: 400

‍

Message: Invalid amount specified

‍

Causes:

• Negative amount
• Amount exceeds original purchase
• Zero amount for non-authorization purchase

‍

Resolution:

• Ensure the amount is positive
• For partial captures/refunds, ensure the amount ≤ remaining

‍

capture_not_allowed

‍

HTTP Status: 409

‍

Message: Capture is not allowed for this purchase

‍

Causes:

• Purchase was not created with skip_capture: true
• Purchase is not in hold status
• Authorization has expired

‍

Resolution:

• Verify the purchase status is hold
• Create a new purchase with skip_capture: true for pre-auth

‍

refund_exceeds_amount

‍

HTTP Status: 400

‍

Message: Refund amount exceeds available balance

‍

Causes:

• Refund amount greater than the original payment
• Previous refunds have reduced the available balance

‍

Resolution:

PYTHON

# Check available refund amount
purchase = get_purchase(purchase_id)
available = purchase['purchase']['total'] - purchase.get('refunded_amount', 0)

‍

Payment Method Errors

payment_method_not_available

‍

HTTP Status: 400

‍

Message: Payment method not available

‍

Causes:

• Payment method not enabled for your merchant
• Payment method not supported for the currency
• Payment method excluded by payment_method_whitelist

‍

Resolution:

1. Check the enabled payment methods
2. Verify currency support for the payment method
3. Review payment_method_whitelist in request

‍

recurring_token_not_found

‍

HTTP Status: 404

‍

Message: Recurring token not found

‍

Causes:

• Invalid token ID
• Token has been deleted
• The token belongs to a different client

‍

Resolution:

1. List client tokens: GET /clients/{id}/recurring_tokens/
2. Verify the token ID is correct
3. Re-tokenize if necessary

‍

recurring_token_expired

‍

HTTP Status: 409

‍

Message: Recurring token has expired

‍

Causes:

• The card has expired
• Token validity period exceeded
• Mandate expired (DebiCheck)

‍

Resolution:

• Request the customer to re-tokenize payment method

‍

card_declined

‍

HTTP Status: 422

‍

Message: Card was declined

‍

Decline Reasons:

‍

3ds_authentication_failed

‍

HTTP Status: 422

‍

Message: 3D Secure authentication failed

‍

Causes:

• Customer failed 3DS challenge
• 3DS timeout
• Customer cancelled authentication

‍

Resolution:

• The customer should retry with the correct credentials
• Ensure the 3DS page loads correctly

‍

Client Errors

client_not_found

‍

HTTP Status: 404

‍

Message: Client not found

‍

Resolution:

1. Verify client ID is correct
2. Create a client if it doesn't exist

‍

duplicate_client

‍

HTTP Status: 409

‍

Message: Client with this email already exists

‍

Causes:

• Attempting to create a client with an existing email

‍

Resolution:

• Search for existing client: GET /clients/?email=customer@example.com
• Use existing client ID

‍

Billing Template Errors

billing_template_not_found

‍

HTTP Status: 404

‍

Message: Billing template not found

‍

subscriber_already_exists

‍

HTTP Status: 409

‍

Message: Client is already subscribed to this template

‍

Resolution:

• Check existing subscription status
• Update existing subscription instead of creating new one

‍

subscription_inactive

‍

HTTP Status: 409

‍

Message: Subscription is not active

‍

Causes:

• subscription_active: false on template
• Subscription has been cancelled

‍

Webhook Errors

webhook_url_invalid

‍

HTTP Status: 400

‍

Message: Invalid webhook URL

‍

Requirements:

• Must be HTTPS
• Must be publicly accessible
• Must respond within 5 seconds

‍

webhook_url_unreachable

‍

HTTP Status: 400

‍

Message: Webhook URL is not reachable

‍

Resolution:

1. Verify URL is publicly accessible
2. Check firewall rules
3. Ensure the SSL certificate is valid

‍

Rate Limiting Errors

rate_limit_exceeded

‍

HTTP Status: 429

‍

Message: Rate limit exceeded

‍

Response Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1619740860

‍

Resolution:

1. Implement exponential backoff
2. Cache responses where possible
3. Batch operations when available

‍

Retry Logic:

PYTHON

import time

def api_request_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        response = func()
        if response.status_code != 429:
            return response

        reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
        wait_time = max(reset_time - time.time(), 2 ** attempt)
        time.sleep(wait_time)

    raise Exception("Rate limit exceeded after retries")

‍

Direct Post Errors

direct_post_expired

‍

HTTP Status: 400

‍

Message: Direct post URL has expired

‍

Causes:

• URL validity is 15 minutes
• URL has already been used

‍

Resolution:

• Create a new purchase for the fresh direct post URL

‍

invalid_card_data

‍

HTTP Status: 400

‍

Message: Invalid card data submitted

‍

Field Validation:

‍

Error Handling Best Practices

1. Always Check HTTP Status

PYTHON

response = requests.post(url, json=data, headers=headers)

if response.status_code == 201:
    # Success - process response
    purchase = response.json()
elif response.status_code == 400:
    # Validation error - show user-friendly message
    errors = response.json()
    handle_validation_errors(errors)
elif response.status_code == 401:
    # Auth error - check credentials
    refresh_credentials()
elif response.status_code == 429:
    # Rate limited - retry with backoff
    retry_with_backoff()
else:
    # Other error - log and alert
    log_error(response)

‍

2. Display User-Friendly Messages

PYTHON

ERROR_MESSAGES = {
    'card_declined': 'Your card was declined. Please try a different payment method.',
    'insufficient_funds': 'Insufficient funds. Please use a different card.',
    'expired_card': 'Your card has expired. Please use a valid card.',
    '3ds_authentication_failed': 'Authentication failed. Please try again.',
    'invalid': 'Please check your information and try again.'
}

def get_user_message(error_code):
    return ERROR_MESSAGES.get(error_code, 'An error occurred. Please try again.')

‍

3. Log Errors for Debugging

PYTHON

import logging

def log_api_error(response, request_data):
    logging.error(
        "API Error",
        extra={
            'status_code': response.status_code,
            'response_body': response.text,
            'request_url': response.url,
            'request_data': sanitize_sensitive_data(request_data)
        }
    )

‍

4. Implement Retry Logic

PYTHON

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=10),
    retry=lambda e: isinstance(e, RetryableError)
)
def make_api_request():
    response = requests.post(...)
    if response.status_code in [429, 502, 503]:
        raise RetryableError()
    return response

‍

Error Code Quick Reference