Errors

All API errors are returned in a consistent JSON format with an error object containing structured information about what went wrong. The error format follows Stripe’s API error conventions for consistency and familiarity.

Error response structure

Response format

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Customer not found",
    "param": "customer_id",
    "timestamp": "2025-01-13T12:00:00Z",
    "doc_url": "https://docs.gettrxn.com/errors#resource-not-found"
  }
}

Error attributes

string

required

The category of error. See error types below.

string

required

A short string indicating the specific error. See error codes below.

string

required

A human-readable message providing details about the error.

string

If the error is parameter-specific, the name of the parameter related to the error. May be null.

string

required

ISO 8601 timestamp of when the error occurred.

string

required

URL to documentation about this error type.

HTTP status codes

The API uses conventional HTTP response codes to indicate success or failure:

Code	Status	Description
200	OK	Request succeeded.
201	Created	Resource was successfully created.
204	No Content	Request succeeded with no response body (e.g., DELETE).
400	Bad Request	Invalid request syntax or missing required parameters.
401	Unauthorized	No valid API token provided.
403	Forbidden	The API token lacks permissions for the requested operation.
404	Not Found	The requested resource doesn’t exist or is not accessible.
422	Unprocessable Entity	Request was valid but contained invalid parameter values.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Something went wrong on the server.

Error types

The type field categorizes the error:

Type	Description
`invalid_request_error`	The request had invalid parameters or referenced a non-existent resource. Most common error type.
`api_error`	Server-side errors or temporary issues. These are rare.
`authentication_error`	Invalid or missing API credentials.
`address_error`	Cryptocurrency address validation failures.

Error codes

The code field provides a programmatic identifier for handling specific errors:

Code	HTTP Status	Description
`resource_not_found`	404	The requested resource (customer, invoice, price, etc.) was not found.
`parameter_missing`	400	A required parameter was not provided.
`parameter_invalid`	422	A parameter value was invalid or failed validation.
`invalid_credentials`	401	The API token is invalid or expired.
`address_invalid`	422	The cryptocurrency address is invalid.
`rate_limit_error`	429	Too many requests in a short period.
`verification_failed`	422	Verification (e.g., Turnstile) failed.
`external_api_error`	502	An external service dependency failed.
`internal_server_error`	500	An unexpected server error occurred.

Common error examples

Resource not found (404)

When requesting a resource that doesn’t exist or belongs to another account:

GET /api/v1/customers/cus_nonexistent

Response

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Customer not found",
    "param": "id",
    "timestamp": "2025-01-13T12:00:00Z",
    "doc_url": "https://docs.gettrxn.com/errors#resource-not-found"
  }
}

Validation error (422)

When creating or updating a resource with invalid data:

POST /api/v1/customers
Content-Type: application/json

{"email": "invalid-email"}

Response

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Email is invalid",
    "param": "email",
    "timestamp": "2025-01-13T12:00:00Z",
    "doc_url": "https://docs.gettrxn.com/errors#parameter-invalid"
  }
}

Nested resource not found (404)

When a nested resource reference is invalid:

POST /api/v1/invoices
Content-Type: application/json

{
  "customer_id": "cus_abc123",
  "line_items": [
    {"price_id": "pri_nonexistent", "quantity": 1}
  ]
}

Response

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Price not found: pri_nonexistent",
    "param": "line_items[][price_id]",
    "timestamp": "2025-01-13T12:00:00Z",
    "doc_url": "https://docs.gettrxn.com/errors#resource-not-found"
  }
}

Authentication error (401)

When the API token is missing or invalid:

GET /api/v1/customers
# No Authorization header

Response

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credentials",
    "message": "Invalid or missing API token",
    "param": null,
    "timestamp": "2025-01-13T12:00:00Z",
    "doc_url": "https://docs.gettrxn.com/errors#invalid-credentials"
  }
}

Handling errors

Programmatic error handling

Use the type and code fields to handle errors programmatically:

response = api_client.create_invoice(params)

if response.error?
  case response.error.code
  when "resource_not_found"
    # Handle missing resource (customer, price, etc.)
    log_error("Resource not found: #{response.error.param}")
  when "parameter_invalid"
    # Handle validation errors
    show_validation_error(response.error.param, response.error.message)
  when "rate_limit_error"
    # Implement exponential backoff
    retry_with_backoff
  else
    # Handle unexpected errors
    log_and_alert(response.error)
  end
end

try {
  await createInvoice(invoiceData);
} catch (error) {
  if (error.response?.data?.error) {
    const apiError = error.response.data.error;
    // Display the message to the user
    showNotification(apiError.message, 'error');

    // Highlight the problematic field if param is set
    if (apiError.param) {
      highlightField(apiError.param);
    }
  }
}

Best practices

Use the code field for programmatic handling, not the message field. Messages may change over time while codes remain stable.

Always check for the error object in non-2xx responses.
Use code for programmatic handling, not message (messages may change).
Display message to users — it is designed to be human-readable.
Use param to highlight form fields that need correction.
Log timestamp and full error for debugging.
Implement exponential backoff for rate_limit_error.
Check doc_url for detailed documentation about specific errors.

Rate limiting

When you exceed rate limits, you will receive:

{
  "error": {
    "type": "invalid_request_error",
    "code": "rate_limit_error",
    "message": "Too many requests. Please retry after 60 seconds.",
    "param": null,
    "timestamp": "2025-01-13T12:00:00Z",
    "doc_url": "https://docs.gettrxn.com/errors#rate-limit-error"
  }
}

Implement exponential backoff when retrying rate-limited requests. Do not retry immediately or in a tight loop.

Support

For questions about API errors or unexpected error responses, contact support with:

The full error response JSON
The request that caused the error (excluding sensitive data)
The timestamp of the error

Introduction

Core resources

Billing

Crypto

Webhooks

Error response structure

Response format

Error attributes

HTTP status codes

Error types

Error codes

Common error examples

Resource not found (404)

Validation error (422)

Nested resource not found (404)

Authentication error (401)

Handling errors

Programmatic error handling

Best practices

Rate limiting

Support

​Error response structure

​Response format

​Error attributes

​HTTP status codes

​Error types

​Error codes

​Common error examples

​Resource not found (404)

​Validation error (422)

​Nested resource not found (404)

​Authentication error (401)

​Handling errors

​Programmatic error handling

​Best practices

​Rate limiting

​Support

Error response structure

Response format

Error attributes

HTTP status codes

Error types

Error codes

Common error examples

Resource not found (404)

Validation error (422)

Nested resource not found (404)

Authentication error (401)

Handling errors

Programmatic error handling

Best practices

Rate limiting

Support