Error reference

Every error tells you exactly what went wrong and how to fix it.

Each API error includes a docs_url that links directly to the relevant entry on this page. No guessing, no searching, the error response itself points you to the fix.

Browse catalog API reference

Metric

Value

Metric

Total error codes

Value

21 codes across 9 categories

Metric

Self-documenting

Value

Every response includes docs_url pointing to this page

Metric

Retryable errors

Value

6 of 21 errors are safe to retry

Metric

SDK support

Value

Error classes expose code, docsUrl, and retryable fields

Overview

Errors that teach instead of frustrate.

Every Payvra API error response follows the same structure: a machine-readable code, a human-readable message, and a docs_url that links to this catalog. The error response itself contains everything a developer needs to diagnose and resolve the issue.

Errors are organized into 9 categories. Each code maps to a specific HTTP status and indicates whether the request is safe to retry.

A single response shape for every error, every endpoint.

The reliability_code is the stable identifier for programmatic handling. The docs_url links to the anchor for that specific error on this page.

API error response

Error response shape

1{
2  "error": {
3    "code": "auth.key_missing",
4    "message": "No API key provided. Include your key in the Authorization header as: Bearer sk_test_...",
5    "data": {
6      "reliability_code": "auth.key_missing",
7      "category": "authentication",
8      "retryable": false,
9      "docs_url": "https://payvra.com/docs/errors#auth.key_missing",
10      "http_status": 401
11    }
12  }
13}

SDK error handling

Error handling with SDK

1import Payvra from "payvra";
2
3const payvra = new Payvra({ apiKey: process.env.PAYVRA_KEY! });
4
5try {
6  const payment = await payvra.payments.create({
7    amount: "100.00",
8    currency: "USDC",
9    chain: "solana",
10  });
11} catch (err) {
12  if (err instanceof Payvra.APIError) {
13    console.error(err.code);       // "auth.key_missing"
14    console.error(err.status);     // 401
15    console.error(err.docsUrl);    // "https://payvra.com/docs/errors#auth.key_missing"
16    console.error(err.retryable);  // false
17  }
18}

Field

Purpose

code

Stable dot-notation identifier (e.g. auth.key_missing). Use this for programmatic error handling.

message

Human-readable description safe to display to developers. Includes actionable remediation steps.

data.reliability_code

Same value as code. Explicit field for error tracking and observability systems.

data.category

Error category (authentication, validation, etc.) for grouping in dashboards.

data.retryable

Whether the request can be retried. Use this to decide between retry and user-facing error.

data.docs_url

Direct link to the error entry on this page. Include in logs for instant debugging.

data.http_status

The HTTP status code returned with this error. Matches the response status.

Error catalog

Every error code, what triggers it, and how to resolve it.

Click any error to expand its description, cause, fix, and code example. Use the search bar to find errors by code, message, or HTTP status.

Authentication

Errors related to identity, missing, malformed, expired, or revoked credentials.

Authorization

The identity is valid but lacks permission for the requested action.

Validation

The request shape or values do not satisfy the endpoint schema.

Not Found

The referenced resource does not exist in the current environment.

Conflict

The request conflicts with existing resource state.

Rate Limit

The caller has exceeded the allowed request rate.

Dependency

An internal infrastructure component is temporarily degraded.

Internal

An unexpected server-side failure outside all other categories.

Payment

Payment-specific errors related to underpayments, wallet rejections, and conversion failures.

Errors that teach instead of frustrate.

Errors are organized into 9 categories. Each code maps to a specific HTTP status and indicates whether the request is safe to retry.

1{ 2 "error": { 3 "code": "auth.key_missing", 4 "message": "No API key provided. Include your key in the Authorization header as: Bearer sk_test_...", 5 "data": { 6 "reliability_code": "auth.key_missing", 7 "category": "authentication", 8 "retryable": false, 9 "docs_url": "https://payvra.com/docs/errors#auth.key_missing", 10 "http_status": 401 11 } 12 } 13}

1import Payvra from "payvra"; 2 3const payvra = new Payvra({ apiKey: process.env.PAYVRA_KEY! }); 4 5try { 6 const payment = await payvra.payments.create({ 7 amount: "100.00", 8 currency: "USDC", 9 chain: "solana", 10 }); 11} catch (err) { 12 if (err instanceof Payvra.APIError) { 13 console.error(err.code); // "auth.key_missing" 14 console.error(err.status); // 401 15 console.error(err.docsUrl); // "https://payvra.com/docs/errors#auth.key_missing" 16 console.error(err.retryable); // false 17 } 18}