Errors

The AnySpend Platform API uses a consistent, structured error format across all endpoints. Errors follow the Stripe convention -- a JSON object with an error key containing the type, code, human-readable message, and (where applicable) the parameter that caused the error.

Error response format

Every error response has this shape:

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_field",
    "message": "The 'name' field is required.",
    "param": "name"
  }
}

Error types

Error types group errors into broad categories. Use these for top-level error handling.

Error codes

Error codes provide specific, machine-readable identifiers for each error condition.

Request validation errors

Authentication and authorization errors

Resource errors

Rate limiting and idempotency errors

Server errors

HTTP status codes

Example error responses

Missing required field

bash
curl -X POST https://platform-api.anyspend.com/api/v1/payment-links \
  -H "Authorization: Bearer asp_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": "10000000" }'

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_field",
    "message": "The 'name' field is required.",
    "param": "name"
  }
}

Invalid Ethereum address

bash
curl -X POST https://platform-api.anyspend.com/api/v1/payment-links \
  -H "Authorization: Bearer asp_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Link",
    "token_address": "not-an-address",
    "chain_id": 8453,
    "recipient_address": "0xabc123..."
  }'

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_address",
    "message": "The 'token_address' field must be a valid Ethereum address (0x + 40 hex characters).",
    "param": "token_address"
  }
}

Authentication failure

bash
curl https://platform-api.anyspend.com/api/v1/payment-links \
  -H "Authorization: Bearer asp_live_expired_key..."

json
{
  "error": {
    "type": "authentication_error",
    "code": "key_expired",
    "message": "This API key has expired."
  }
}

Insufficient permissions

bash
# A read-only key trying to create a resource
curl -X POST https://platform-api.anyspend.com/api/v1/payment-links \
  -H "Authorization: Bearer asp_live_readonly_key..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Test" }'

json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_permissions",
    "message": "This API key does not have 'write' permission."
  }
}

Resource not found

bash
curl https://platform-api.anyspend.com/api/v1/payment-links/pl_nonexistent \
  -H "Authorization: Bearer asp_live_abc123..."

json
{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "No payment_link found with id 'pl_nonexistent'."
  }
}

Rate limit exceeded

json
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 42 seconds."
  }
}

Idempotency conflict

json
{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_conflict",
    "message": "An idempotency key was used with a different request body."
  }
}

Handling errors in code

TypeScript / JavaScript

typescript
async function createPaymentLink(data: PaymentLinkInput) {
  const response = await fetch(
    "https://platform-api.anyspend.com/api/v1/payment-links",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.ANYSPEND_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(data),
    }
  );

  const body = await response.json();

  if (!response.ok) {
    const error = body.error;

    switch (error.type) {
      case "invalid_request_error":
        // Fix the request -- check error.param for the bad field
        console.error(`Invalid request: ${error.message} (field: ${error.param})`);
        break;

      case "authentication_error":
        // Check your API key -- it may be expired or revoked
        console.error(`Auth failed: ${error.message}`);
        break;

      case "permission_error":
        // Upgrade the API key permissions
        console.error(`Insufficient permissions: ${error.message}`);
        break;

      case "rate_limit_error":
        // Back off and retry
        console.warn(`Rate limited: ${error.message}`);
        await sleep(5000);
        return createPaymentLink(data); // retry
        break;

      case "not_found_error":
        console.error(`Not found: ${error.message}`);
        break;

      case "idempotency_error":
        // The idempotency key was reused with different data
        console.error(`Idempotency conflict: ${error.message}`);
        break;

      case "api_error":
        // Server error -- retry with exponential backoff
        console.error(`Server error: ${error.message}`);
        break;
    }

    throw new Error(`AnySpend API error: ${error.code} - ${error.message}`);
  }

  return body;
}

Python

python
import requests
import time

def create_payment_link(data: dict) -> dict:
    response = requests.post(
        "https://platform-api.anyspend.com/api/v1/payment-links",
        headers={
            "Authorization": f"Bearer {os.environ['ANYSPEND_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=data,
    )

    body = response.json()

    if not response.ok:
        error = body["error"]
        error_type = error["type"]

        if error_type == "rate_limit_error":
            time.sleep(5)
            return create_payment_link(data)  # retry

        if error_type == "authentication_error":
            raise PermissionError(f"Auth failed: {error['message']}")

        if error_type == "invalid_request_error":
            raise ValueError(
                f"Bad request on field '{error.get('param', 'unknown')}': "
                f"{error['message']}"
            )

        raise Exception(f"AnySpend API error: {error['code']} - {error['message']}")

    return body

Best practices

typescript
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      const isRetryable =
        err.status === 429 || err.status === 500;

      if (!isRetryable || attempt === maxRetries) throw err;

      const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw new Error("Unreachable");
}