Error handling - Upwell Developer Docs

Error Response Format

Upwell API errors are flat JSON objects — a message string, sometimes with a machine code alongside it:

{
  "error": "Not-NULL violation. null value in column \"shipment_id\" of relation \"shipments\" violates not-null constraint",
  "code": "constraint-violation"
}

There is no nested error envelope, no details object, and no timestamp field. Parse error as the human-readable message and treat code (when present, e.g. constraint-violation, bad-request) as the machine-readable category.

One exception: a failed authentication (401) returns an empty body — don’t assume every error response parses as JSON.

HTTP Status Codes

The codes you will actually encounter:

Status Code	Meaning	What to do
`200`	Success — including creates and action endpoints.	Note: action endpoints can report business errors inside a 200 body — see below.
`400`	Malformed or invalid request: missing required field, duplicate external key, wrong wrapper, non-integer money.	Fix the payload — see the error messages table. Not retryable as-is.
`401`	Missing, invalid, or revoked API key. Empty body.	Check the `Authorization` header and the key’s status — see Authentication.
`404`	The path doesn’t exist (wrong URL or method-path combination).	A missing record on a valid path does not 404 — see Not-found semantics.
`405`	Method not supported on that path (e.g. `GET` on a `POST`-only endpoint).	Check the endpoint’s methods in the reference.
`500`	Server-side error.	Safe to retry with exponential backoff — but see the retry rules for `POST`.

Two codes conspicuously absent, on purpose:

201 is not used — successful creates return 200.
429 is not used — see Rate limiting below.

Business errors inside a 200

The approval action endpoints report failure in the response body, not the HTTP status. A POST /api/rest/invoices/{id}/approve that can’t proceed still returns 200:

{
  "approveInvoice": {
    "success": false,
    "error": {
      "code": "OPEN_EXCEPTIONS",
      "message": "Cannot approve invoice with open exceptions"
    },
    "exceptions": [ { "id": "...", "type": "...", "status": "OPEN" } ]
  }
}

Code	Meaning	Fix
`OPEN_EXCEPTIONS`	The invoice has unresolved exceptions.	Resolve them, or re-call with `overrideExceptions=true` to force approval.
`INVOICE_NOT_FOUND`	The invoice doesn’t exist or isn’t in an approvable state.	Verify the id and the invoice’s current `status`.

Always check the nested success / error fields on action endpoints — checking only the HTTP status will miss these.

Real error messages and their fixes

The messages you’ll actually see in 400 responses, and what each one means:

Error contains	Cause	Fix
`Uniqueness violation`	Re-`POST` of an existing `(sourceSystem, sourceSystemId)` pair — or a second `CUSTOMER_BILLING` address on one customer.	First sync is `POST`, updates are `PUT` — semantics differ per resource; see idempotent upserts.
`Not-NULL violation. null value in column "..."`	A required field with no server default was omitted — the column name is in the message (e.g. `shipment_id`, `balance`).	Send the field; see required fields without defaults.
`Check constraint violation. ... documents_source_system_pair_nullity_chk`	A document was given `sourceSystem` without `sourceSystemId` (or vice versa).	Send both or neither.
`The value ... lies outside the bounds or is not an integer`	Money sent as a float (`2847.5`).	All monetary fields are integer cents: `284750`.
`bad-request: Unexpected variable ...`	Payload not wrapped correctly, or an unknown field name.	Singular creates wrap in `{ "input": { ... } }`; bulk endpoints use `{ "inputs": [ ... ] }` — see wrapping POST payloads.
`DOCUMENT_ALREADY_UPLOADED`	Re-requesting a presigned upload URL for a `(sourceSystem, sourceSystemId)` pair that already uploaded successfully.	Fetch the existing document instead; see the PO & vendor invoice guide.

Not-found semantics

A lookup by an id that doesn’t exist — deleted, mistyped, or belonging to a different organization — is not an HTTP error. The single-resource GETs declare a nullable resource and return it inside a 200:

{ "customer": null }

List endpoints likewise return empty arrays. So:

Check the body, not just the status, when verifying a record exists.
A real 404 means the path is wrong, not that the record is missing.
Remember Upwell ids are prefixed strings (cus_…, inv_…, cari_…) — a truncated or unprefixed id is a common cause of “exists in the dashboard but null over the API.”
To find records by your own keys instead, use the POST /<resource>/search endpoints (see Integration patterns).

Rate limiting

The Upwell API does not currently enforce rate limits. There are no 429 responses, no X-RateLimit-* headers, and no Retry-After header — don’t build handling machinery for them. If you do observe a 429, it originated from infrastructure on your side (a proxy or gateway), not from Upwell. That’s a description of today’s behavior, not an invitation: keep client concurrency bounded and batch with the bulk-* endpoints where they exist. If limits are introduced, they’ll be announced in the changelog.

What is safe to retry

Network failures and 5xx — retry with exponential backoff and jitter.
POST retries need per-resource care. A retried create is not uniformly safe: customers/shipments/invoices reject duplicates with 400 Uniqueness violation, carriers silently no-op, and carrier invoices deduplicate asynchronously — read idempotent upserts before writing retry logic.
400 is never retryable as-is — the request itself is wrong; fix the payload.
401 is not retryable — fix the credential.

async function apiCall(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status >= 500) {
        // Server-side — back off and retry
        await new Promise((r) => setTimeout(r, 2 ** attempt * 1000 + Math.random() * 250));
        continue;
      }

      if (!response.ok) {
        // 4xx — not retryable; surface the flat error body (may be empty on 401)
        const text = await response.text();
        throw new Error(`API error ${response.status}: ${text || '(empty body)'}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

Getting Help

If an error doesn’t match anything on this page:

Capture the full exchange — endpoint, HTTP method, request body (redact the API key), the complete response body, and the timestamp.
Note the last 4 characters of the API key you used (never send the full key).
Contact support at support@upwell.com.

For platform-level troubleshooting beyond API errors, see the Troubleshooting guide.

​Error Response Format

​HTTP Status Codes

​Business errors inside a 200

​Real error messages and their fixes

​Not-found semantics

​Rate limiting

​What is safe to retry

​Getting Help

Error Response Format

HTTP Status Codes

Business errors inside a 200

Real error messages and their fixes

Not-found semantics

Rate limiting

What is safe to retry

Getting Help