Troubleshooting Guide - Upwell Developer Docs

Quick Troubleshooting Checklist

Before You Start

Before diving into specific issues, verify these basics:

✅ Your API key is valid and hasn’t been revoked
✅ You’re using the correct base URL: https://api.upwell.com
✅ All required headers are included
✅ Request format follows the API specification
✅ You have sufficient permissions for the operation

Common Issues and Solutions

Authentication Problems

API Key Not Working

Symptoms: Getting 401 Unauthorized errorsSolutions:

Verify the header format The key is an opaque string — send it exactly as issued, bare or with a Bearer prefix (both are accepted):
curl -H "Authorization: YOUR_API_KEY" https://api.upwell.com/api/rest/invoices curl -H "Authorization: Bearer YOUR_API_KEY" https://api.upwell.com/api/rest/invoices
Watch for copy-paste issues: whitespace, quotes, or a truncated key.
Confirm the key wasn’t revoked
- Log into your Upwell dashboard
- Navigate to Account → API keys
- Confirm the key still appears in the list. Keys don’t expire, but a revoked key stops working immediately.
Rotate the key
- Create a new key (Add API Key), update your application with it, then revoke the old one. The key value is shown only once at creation.
- See Authentication for the full flow.

Permission Denied Errors

Symptoms: Getting 403 Forbidden errorsSolutions:

Check User Permissions
- Verify your user account has the necessary permissions
- Contact your administrator to update permissions
Check which organization the key belongs to
- An API key is scoped to the one Upwell organization it was created in — it cannot read or write another organization’s data
- If you work with multiple Upwell organizations, confirm you’re using the right organization’s key
Resource Access Rights
- Ensure you have access to the specific customer/carrier data
- Verify organization-level permissions

Data Integration Issues

Invoice Upload Failures

Symptoms: Invoices not processing correctlySolutions:

Use the right upload path for the file
- The inline base64 document endpoints reject payloads past a few MB — use the two-step presigned upload for anything larger.
- For carrier-invoice documents, the presigned flow is the only path that runs AI classification — a PDF sent through a base64 endpoint is filed but never classified or parsed.
Verify Email Ingestion
- Emailed invoices must go to your organization’s dedicated inbound address — find or configure it under Email Settings in the dashboard (see the quickstart), and confirm senders are forwarding to exactly that address.
Check classification status
- A document’s type stays UNKNOWN while classification is in flight; one still UNKNOWN well past upload needs manual review rather than a retry — see Knowing when a carrier invoice is processed.

TMS Integration Problems

Symptoms: Shipment data not syncingSolutions:

Connection Testing

curl -X GET "https://api.upwell.com/api/rest/shipments" \
  -H "Authorization: YOUR_API_KEY"

Data Format Validation
- Ensure shipment IDs match between systems
- Verify date formats are ISO 8601 compliant
- Check required fields are populated
Webhook Configuration
- Verify webhook URLs are accessible
- Check SSL certificate validity
- Confirm webhook authentication is configured

Payment Processing Issues

Symptoms: Payments not applying to invoicesSolutions:

Check the payment’s line items
- A payment applies to invoices through its line items — each line item must carry the target invoiceId and an integer-cents totalAmount. A payment with no line items applies to nothing. See Customer payments.
Verify the application amount
- A linked line item automatically recalculates the target invoice’s balance and payment status in the standard API-managed model. If totalAmountWithFees is present, it takes precedence over totalAmount; make sure it contains only the principal applied to the invoice.
Correct reversals on the original line item
- Changing only a payment or line-item status does not unapply the amount. Update or delete the original line item and confirm the invoice reopens as expected.
Manual Payment Application
- Payments recorded inside Upwell can be applied from the dashboard — see Accounts receivable management.

Performance and Rate Limiting

Slow API Response Times

Symptoms: API calls taking longer than expectedSolutions:

Optimize Query Parameters

// Use pagination for large datasets
const response = await fetch(
  'https://api.upwell.com/api/rest/invoices?limit=50&offset=0'
);

Filter server-side with the search endpoints

// POST /<resource>/search takes a Hasura-style `where` body —
// filter by date range instead of paging the whole collection
const response = await fetch('https://api.upwell.com/api/rest/invoices/search', {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    where: { createdAt: { _gte: '2026-07-01', _lt: '2026-08-01' } },
    limit: 50,
    offset: 0,
  }),
});

Use Bulk Operations — where a bulk endpoint exists Only some resources have a bulk-* create endpoint (bulk-customers, bulk-carriers, bulk-bills, bulk-carrier-invoices, bulk-customer-payments, bulk-customer-payment-line-items, bulk-carrier-payment-line-items). Invoices have no bulk endpoint — there is no /api/rest/bulk-invoices; loop individual POST/PUT calls to /api/rest/invoices instead.

// Bulk-create multiple customers in one request — note the `inputs` (plural) wrapper
const bulkCreate = await fetch(
  'https://api.upwell.com/api/rest/bulk-customers',
  {
    method: 'POST',
    headers: { Authorization: 'YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ inputs: customerArray }),
  }
);

Getting 429 Too Many Requests errors

The Upwell API does not currently enforce rate limits — it never returns 429 and sends no X-RateLimit-* or Retry-After headers. A 429 you observe is coming from infrastructure on your side (a corporate proxy, API gateway, or serverless platform limit), so debug it there.Keep your client polite anyway — bound your concurrency, and retry only server-side failures:

import time
import random

def api_call_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code >= 500:
            # Server-side error — back off and retry
            time.sleep((2 ** attempt) + random.uniform(0, 1))
            continue

        return response  # 2xx and 4xx are final — don't blind-retry 4xx

See Error handling for what is and isn’t safe to retry.

Data Quality and Validation

Validation Errors

Symptoms: Getting 400 Bad Request responsesThe error body is a flat message string that names the problem — match on it:

Error contains	Fix
`Not-NULL violation. null value in column "..."`	Send the named field — e.g. `shipmentId` on shipments, `balance` on invoices. See required fields.
`Uniqueness violation`	You re-`POST`ed an existing `(sourceSystem, sourceSystemId)` — update with `PUT` instead.
`The value ... is not an integer`	Money must be integer cents: `284750`, never `2847.50`.
`bad-request: Unexpected variable ...`	Wrap create payloads in `{ "input": { ... } }` (bulk endpoints use `inputs`), and check the field name against the reference — fields are `camelCase` (`customerId`, `dueDate`).

Validate before sending:

// Field names are camelCase; money is integer cents
const invoice = {
  customerId: 'cus_abc123',
  totalAmount: 450000, // $4,500.00
  balance: 450000, // required — equals totalAmount for a new invoice
  dueDate: '2026-08-30',
};
if (!Number.isInteger(invoice.totalAmount)) {
  throw new Error('totalAmount must be integer cents');
}

The full message-to-fix table lives in Error handling.

Data Not Found

Symptoms: A record you expect isn’t coming backSolutions:

Check the body, not the status code
- A lookup for a missing record does not return 404: the single-resource GETs return 200 with a null resource ({ "customer": null }), and lists return empty arrays. A real 404 means the URL path itself is wrong.
Verify Resource IDs
- Upwell ids are prefixed strings (cus_…, inv_…, cari_…) — check for truncation or a stripped prefix
- Confirm the record wasn’t deleted, and that your API key belongs to the organization that owns it

Search by your own keys instead

# POST /<resource>/search takes a JSON body with a where filter
curl -X POST https://api.upwell.com/api/rest/invoices/search \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "where": { "number": { "_eq": "INV-001" } }, "limit": 10 }'

Testing and Debugging

API Testing Tools

Using Curl for Testing

Basic Request Testing:

# Test authentication
curl -v -H "Authorization: YOUR_API_KEY" \
  https://api.upwell.com/api/rest/invoices

# Test with verbose output for debugging — note the input wrapper,
# camelCase fields, and integer-cents money
curl -v -X POST https://api.upwell.com/api/rest/invoices \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"customerId": "cus_abc123", "totalAmount": 10000, "balance": 10000}}'

Using Postman for API Testing

Setting Up Postman:

Import the Upwell OpenAPI specification
Configure environment variables:
- base_url: https://api.upwell.com
- api_key: YOUR_API_KEY
Set up authentication in the Authorization tab
Use the Collection Runner for batch testing

Logging and Monitoring

Request Logging

Essential Logging Information:

import logging

def log_api_request(method, url, status_code, response_time):
    logging.info(f"API Request: {method} {url} - {status_code} ({response_time}ms)")

    if status_code >= 400:
        logging.error(f"API Error: {status_code} - Check error response for details")

Performance Monitoring

Key Metrics to Track:

Response times by endpoint
Error rates by status code and error message
Success/failure ratios

const metrics = {
  totalRequests: 0,
  successfulRequests: 0,
  averageResponseTime: 0,
  errorsByCode: {}
};

Getting Additional Help

Support Channels

Technical Support

For API and integration issues

API Documentation

Complete endpoint reference

Error Handling Reference

Real error shapes, messages, and retry rules

Implementation Guide

Step-by-step setup instructions

When Contacting Support

Include the following information in your support request:

Error Details
- Complete error message and code
- Request timestamp
- Endpoint being called
Request Information
- HTTP method and URL
- Request headers (excluding API key)
- Request body (if applicable)
Environment Details
- Programming language and version
- Library/SDK versions
- Network configuration (if relevant)
Steps to Reproduce
- Detailed steps that led to the issue
- Expected vs. actual behavior
- Frequency of occurrence

Best Practices for Smooth Operation

Keep API Keys Secure
- Never commit keys to version control
- Use environment variables
- Rotate keys regularly
Implement Proper Error Handling
- Handle all HTTP status codes appropriately
- Implement retry logic for transient errors
- Log errors for debugging
Monitor API Usage
- Track request volumes and patterns
- Set up alerts for unusual activity
Test Thoroughly
- Test error scenarios in addition to success cases
- Use staging environment for integration testing
- Validate data before sending to API
Stay Updated
- Watch the changelog for API and platform changes — or subscribe to its RSS feed to get them pushed to Slack, email, or a feed reader
- Review documentation updates
- Test new features in staging first

​Quick Troubleshooting Checklist

​Common Issues and Solutions

​Authentication Problems

​Data Integration Issues

​Performance and Rate Limiting

​Data Quality and Validation

​Testing and Debugging

​API Testing Tools

​Logging and Monitoring

​Getting Additional Help

​Support Channels