Error Handling

Error Response Format

When an API request fails, Creem returns a JSON error response:

{
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": 400,
  "error": "Bad Request",
  "message": ["The 'product_id' field is required."],
  "timestamp": 1706889600000
}

Field	Type	Description
`trace_id`	string	Unique identifier for the request (useful for debugging)
`status`	number	HTTP status code
`error`	string	Error category
`message`	string[]	Array of human-readable error messages
`timestamp`	number	Unix timestamp in milliseconds

The trace_id is included in every error response. Include it when contacting support for faster debugging.

HTTP Status Codes

Status	Error	When It Occurs
`400`	Bad Request	Invalid request parameters, malformed JSON, or validation errors
`403`	Forbidden	Invalid API key or insufficient permissions
`404`	Not Found	Requested resource doesn’t exist

Common Error Scenarios

Authentication Errors (403 Forbidden)

Returned when the API key is missing, invalid, or doesn’t have permission for the requested resource.

{
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": 403,
  "error": "Forbidden",
  "timestamp": 1706889600000
}

How to fix:

Verify your API key in the dashboard
Ensure the x-api-key header is included in your request
Check you’re using the correct key for the environment (test vs. production)

curl -X GET https://api.creem.io/v1/products \
  -H "x-api-key: creem_YOUR_API_KEY"

Validation Errors (400 Bad Request)

Returned when request parameters are missing or invalid.

{
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": 400,
  "error": "Bad Request",
  "message": ["product_id must be a string", "success_url must be a valid URL"],
  "timestamp": 1706889600000
}

How to fix:

Check the message array for specific validation errors
Verify all required fields are included
Ensure data types match the expected format

Resource Not Found (404)

Returned when the requested resource doesn’t exist.

{
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": 404,
  "error": "Bad Request",
  "message": ["Product not found"],
  "timestamp": 1706889600000
}

How to fix:

Verify the resource ID is correct
Ensure you’re using the right environment (test vs. production resources are separate)
Check if the resource was deleted

Duplicate Resource (400 Bad Request)

Returned when trying to create a resource that already exists.

{
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": 400,
  "error": "Bad Request",
  "message": ["A resource with this identifier already exists"],
  "timestamp": 1706889600000
}

How to fix:

Use a unique identifier for idempotent requests
Check if the resource already exists before creating

Handling Errors in Code

TypeScript SDK

import { Creem } from 'creem';

const creem = new Creem({ apiKey: process.env.CREEM_API_KEY! });

try {
  const checkout = await creem.checkouts.create({
    productId: 'prod_123',
    successUrl: 'https://example.com/success',
  });
} catch (error) {
  if (error.response) {
    const { trace_id, status, message } = error.response.data;
    console.error(`Error ${status}: ${message.join(', ')}`);
    console.error(`Trace ID: ${trace_id}`);
  }
}

cURL

# The response includes the trace_id for debugging
curl -X POST https://api.creem.io/v1/checkouts \
  -H "x-api-key: creem_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "invalid"}' \
  -w "\nHTTP Status: %{http_code}\n"

Environments

Make sure you’re using the correct base URL:

Environment	Base URL
Production	`https://api.creem.io`
Test Mode	`https://test-api.creem.io`

Test mode API keys only work with test-api.creem.io, and production keys only work with api.creem.io.

Need Help?

If you’re experiencing issues:

Check the trace_id in your error response
Join our Discord community for quick help
Contact support with your trace ID for faster debugging

API Documentation

Checkout

Product

Customer

Transactions

Affiliate

License

Discount Code

Subscription

Stats

Customer Credits

Moderation

Error Handling

Error Response Format

HTTP Status Codes

Common Error Scenarios

Authentication Errors (403 Forbidden)

Validation Errors (400 Bad Request)

Resource Not Found (404)

Duplicate Resource (400 Bad Request)

Handling Errors in Code

TypeScript SDK

cURL

Environments

Need Help?

​Error Response Format

​HTTP Status Codes

​Common Error Scenarios

​Authentication Errors (403 Forbidden)

​Validation Errors (400 Bad Request)

​Resource Not Found (404)

​Duplicate Resource (400 Bad Request)

​Handling Errors in Code

​TypeScript SDK

​cURL

​Environments

​Need Help?

Error Response Format

HTTP Status Codes

Common Error Scenarios

Authentication Errors (403 Forbidden)

Validation Errors (400 Bad Request)

Resource Not Found (404)

Duplicate Resource (400 Bad Request)

Handling Errors in Code

TypeScript SDK

cURL

Environments

Need Help?