Error ReferenceCopy Anchor Link

All PayzCore API errors follow a consistent JSON format. This page documents every error status code, the response structure, common error messages, and how to handle them.

Response FormatCopy Anchor Link

Every error response includes an error field with a human-readable message. Some errors include additional fields for context.

Standard ErrorCopy Anchor Link

{
  "error": "Description of what went wrong"
}

Validation ErrorCopy Anchor Link

When the request body fails validation (wrong type, missing required field, value out of range), the API returns a single generic message. It does not list the failing fields, so check your request against the API Reference.

{
  "error": "Invalid request body"
}

Rate Limit Error (with plan info)Copy Anchor Link

{
  "error": "Daily API call limit exceeded. Upgrade your plan for unlimited access.",
  "limit": 500,
  "plan": "free"
}

HTTP Status CodesCopy Anchor Link

400 Bad RequestCopy Anchor Link

Validation errors caused by invalid parameters, missing required fields, or unsupported values.

How to fix: Compare your request with the API Reference (types, required fields, limits). Correct the request parameters and retry.

401 UnauthorizedCopy Anchor Link

Authentication failed. The API key is missing, invalid, or malformed.

Too many requests with unknown API keys from one IP (30 per minute) return 429 Too many invalid API key attempts. Try again later. instead.

How to fix: Verify your API key is correct and included in the x-api-key header. API keys start with pk_live_. If you lost your key, the project owner can regenerate it from the project settings.

403 ForbiddenCopy Anchor Link

The request was authenticated but is not allowed due to access restrictions.

How to fix: Contact PayzCore support or your account administrator. Deactivated projects cannot make API calls until reactivated.

404 Not FoundCopy Anchor Link

The requested resource does not exist or is not accessible by this API key.

How to fix: Verify the payment ID is correct. Each project can only access its own payments.

409 ConflictCopy Anchor Link

The request conflicts with an existing resource.

Repeating a request is not a 409. When you send the same external_order_id + external_ref + network + token (and amount) again, PayzCore returns 200 with the existing payment and "existing": true. This makes retries safe. The SDKs map every 409 above to IdempotencyError / IdempotencyException; read its message for the exact reason.

429 Too Many RequestsCopy Anchor Link

Rate limit exceeded. There are two types of rate limits:

Per-Minute Rate Limit (burst protection)Copy Anchor Link

Limits the number of requests per API key per minute. Default: 60 requests/minute.

{
  "error": "Rate limit exceeded. Try again later."
}

Response headers (sent only on 429 responses, not on successful ones):

Daily Limit (plan-based)Copy Anchor Link

Limits total API calls per day based on your plan.

{
  "error": "Daily API call limit exceeded. Upgrade your plan for unlimited access.",
  "limit": 500,
  "plan": "free"
}

Response headers (only on 429 responses):

Plan limits:

Admin-configured custom overrides may apply per user.

Capacity Limit (pool mode)Copy Anchor Link

When using pool+micro_amount mode, all available offsets for the requested amount may be exhausted. This 429 has no X-RateLimit-* headers:

{
  "error": "Payment capacity exceeded. Please try again later."
}

How to fix for per-minute limits: Wait for the reset time indicated in the X-RateLimit-Reset header. Implement exponential backoff in your client.

How to fix for daily limits: Wait until midnight UTC, or upgrade to the Pro plan for higher limits.

How to fix for capacity limits: Wait for existing payments on the pool to resolve (paid/expired), or add more static addresses.

500 Internal Server ErrorCopy Anchor Link

An unexpected error occurred on the server.

{
  "error": "Failed to create payment"
}

How to fix: Retry the request with exponential backoff. If the error persists, check the health endpoint and contact support.

Recommended retry strategy:

SDK Error HandlingCopy Anchor Link

The official SDKs map HTTP errors to typed exception classes, making it easy to handle specific error types.

Node.js SDKCopy Anchor Link

import {
  PayzCoreError,
  ValidationError,
  AuthenticationError,
  ForbiddenError,
  NotFoundError,
  RateLimitError,
  IdempotencyError,
} from '@payzcore/node'

try {
  const payment = await payzcore.payments.create({
    amount: 50,
    network: 'TRC20',
    externalRef: 'customer-123',
  })
} catch (err) {
  if (err instanceof ValidationError) {
    // 400 - Invalid parameters
    console.error('Validation:', err.message)
  } else if (err instanceof AuthenticationError) {
    // 401 - Invalid API key
    console.error('Auth:', err.message)
  } else if (err instanceof ForbiddenError) {
    // 403 - Project inactive or account suspended
    console.error('Forbidden:', err.message)
  } else if (err instanceof NotFoundError) {
    // 404 - Resource not found
    console.error('Not found:', err.message)
  } else if (err instanceof RateLimitError) {
    // 429 - Rate limited
    console.error('Rate limited:', err.message)
    // retryAfter is a Unix timestamp (seconds), not a duration
    const waitSeconds = Math.max(0, (err.retryAfter ?? 0) - Math.floor(Date.now() / 1000))
    console.error('Retry in', waitSeconds, 'seconds. Daily limit:', err.isDaily)
  } else if (err instanceof IdempotencyError) {
    // 409 - Conflict (see the 409 table above)
    console.error('Conflict:', err.message)
  } else if (err instanceof PayzCoreError) {
    // Other API errors (500, etc.)
    console.error('API error:', err.status, err.message)
  }
}

Error Class HierarchyCopy Anchor Link

All error classes extend PayzCoreError, which extends Error. You can catch PayzCoreError as a catch-all for any API error.

Python SDKCopy Anchor Link

import time
from payzcore import PayzCoreError, ValidationError, RateLimitError

try:
    payment = client.payments.create(
        amount=50, network="TRC20", external_ref="customer-123"
    )
except ValidationError as e:
    print(f"Validation: {e.message}")
except RateLimitError as e:
    # retry_after is a Unix timestamp (seconds), not a duration
    wait = max(0, (e.retry_after or 0) - int(time.time()))
    print(f"Rate limited, retry in {wait}s")
except PayzCoreError as e:
    print(f"API error {e.status}: {e.message}")

PHP SDKCopy Anchor Link

use PayzCore\Exceptions\ValidationException;
use PayzCore\Exceptions\RateLimitException;
use PayzCore\Exceptions\PayzCoreException;

try {
    $payment = $client->payments->create([
        'amount' => 50, 'network' => 'TRC20', 'externalRef' => 'customer-123'
    ]);
} catch (ValidationException $e) {
    echo "Validation: " . $e->getMessage();
} catch (RateLimitException $e) {
    // getRetryAfter() is a Unix timestamp (seconds), not a duration
    $wait = max(0, ($e->getRetryAfter() ?? time()) - time());
    echo "Rate limited, retry in {$wait}s";
} catch (PayzCoreException $e) {
    echo "API error {$e->getStatusCode()}: {$e->getMessage()}";
}

Best PracticesCopy Anchor Link

1. Always check the status code first. Different status codes require different handling strategies.
2. Read the error message on 400 errors. Validation failures return Invalid request body without field details, so compare your request with the API Reference.
3. Implement retry logic for 429 and 500 errors. Use the X-RateLimit-Reset header for rate limits and exponential backoff for server errors.
4. Do not retry 400, 401, 403, or 404 errors. These indicate issues that need to be fixed in your code or configuration, not transient failures.
5. Use external_order_id for idempotency. This prevents duplicate payment creation during retries and returns the existing payment safely.
6. Log error responses. Store the full error response body for debugging and support requests.
7. Use typed SDK exceptions. The official SDKs provide specific error classes that make error handling clean and type-safe.