Skip to main content
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

​
type
string
required
The category of error. See error types below.
​
code
string
required
A short string indicating the specific error. See error codes below.
​
message
string
required
A human-readable message providing details about the error.
​
param
string
If the error is parameter-specific, the name of the parameter related to the error. May be null.
​
timestamp
string
required
ISO 8601 timestamp of when the error occurred.
​
doc_url
string
required
URL to documentation about this error type.

​
HTTP status codes

The API uses conventional HTTP response codes to indicate success or failure:
CodeStatusDescription
200OKRequest succeeded.
201CreatedResource was successfully created.
204No ContentRequest succeeded with no response body (e.g., DELETE).
400Bad RequestInvalid request syntax or missing required parameters.
401UnauthorizedNo valid API token provided.
403ForbiddenThe API token lacks permissions for the requested operation.
404Not FoundThe requested resource doesn’t exist or is not accessible.
422Unprocessable EntityRequest was valid but contained invalid parameter values.
429Too Many RequestsRate limit exceeded.
500Internal Server ErrorSomething went wrong on the server.

​
Error types

The type field categorizes the error:
TypeDescription
invalid_request_errorThe request had invalid parameters or referenced a non-existent resource. Most common error type.
api_errorServer-side errors or temporary issues. These are rare.
authentication_errorInvalid or missing API credentials.
address_errorCryptocurrency address validation failures.

​
Error codes

The code field provides a programmatic identifier for handling specific errors:
CodeHTTP StatusDescription
resource_not_found404The requested resource (customer, invoice, price, etc.) was not found.
parameter_missing400A required parameter was not provided.
parameter_invalid422A parameter value was invalid or failed validation.
invalid_credentials401The API token is invalid or expired.
address_invalid422The cryptocurrency address is invalid.
rate_limit_error429Too many requests in a short period.
verification_failed422Verification (e.g., Turnstile) failed.
external_api_error502An external service dependency failed.
internal_server_error500An 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

​
Best practices

Use the code field for programmatic handling, not the message field. Messages may change over time while codes remain stable.
  1. Always check for the error object in non-2xx responses.
  2. Use code for programmatic handling, not message (messages may change).
  3. Display message to users — it is designed to be human-readable.
  4. Use param to highlight form fields that need correction.
  5. Log timestamp and full error for debugging.
  6. Implement exponential backoff for rate_limit_error.
  7. 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