> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gettrxn.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> Understand the TRXN API error response format, HTTP status codes, error types, error codes, and how to handle errors in your integration.
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
```json theme={null}
{
"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
The category of error. See [error types](#error-types) below.
A short string indicating the specific error. See [error codes](#error-codes) below.
A human-readable message providing details about the error.
If the error is parameter-specific, the name of the parameter related to the error. May be `null`.
ISO 8601 timestamp of when the error occurred.
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:
```bash theme={null}
GET /api/v1/customers/cus_nonexistent
```
```json Response theme={null}
{
"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:
```bash theme={null}
POST /api/v1/customers
Content-Type: application/json
{"email": "invalid-email"}
```
```json Response theme={null}
{
"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:
```bash theme={null}
POST /api/v1/invoices
Content-Type: application/json
{
"customer_id": "cus_abc123",
"line_items": [
{"price_id": "pri_nonexistent", "quantity": 1}
]
}
```
```json Response theme={null}
{
"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:
```bash theme={null}
GET /api/v1/customers
# No Authorization header
```
```json Response theme={null}
{
"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:
```ruby Ruby theme={null}
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
```
```javascript Node.js theme={null}
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.
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:
```json theme={null}
{
"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