invalid_id 🔌 API

API Error: Invalid ID format (not a valid UUID / malformed identifier)

An ID in the URL or body doesn’t have the shape the API expects — a malformed UUID, wrong prefix, or an ID mangled by encoding or whitespace.

Seen on: REST API

Meaning

Many APIs check ID syntax before looking anything up: UUIDs must be 36 characters, prefixed IDs (cus_, pi_, usr_) must carry the right prefix, MongoDB ObjectIds must be 24 hex characters. The error is a 400/422 rather than a 404 because the ID couldn’t possibly exist.

Common causes are trailing whitespace or newlines from copy-paste, URL-encoding, quotes left around the value, or passing the wrong kind of ID (an order number where a database ID is expected).

Common causes

  • Whitespace, quotes or newline around the ID
  • Wrong kind of ID (slug, order number, email) passed as the ID
  • ID truncated or URL-encoded twice
  • Wrong prefix for the object type (cus_ vs pi_)
  • Placeholder like ":id" or "undefined" sent literally

⚡ Quick fix

  1. Trim and log the exact ID being sent
  2. Send the ID exactly as the API returned it
  3. Validate the format client-side before calling

Detailed fix by platform

Node.js

  1. javascript
    const id = String(raw).trim();
if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) throw new Error(`bad id: ${JSON.stringify(raw)}`);

How to diagnose

  1. Value — JSON.stringify the ID to reveal hidden characters
  2. Kind — Is it the ID type the endpoint expects?
  3. Literal — Is it "undefined" or ":id"?

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.