invalid_id API Origin: Application & API OSI layer 7 · Application Last updated 13 Oct 2026

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.

Exact message you may see is not a valid UUIDInvalid UUIDinvalid id formatmust match format "uuid"Input should be a valid UUID
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 not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Application & API. Errors that are often confused with or caused by this one (click to open):

22P02 uuid — ERROR: invalid input syntax for type uuid: "x" (PostgreSQL)22P02 uuid400 — HTTP 400 Bad Request (HTTP)400CastError ObjectId — CastError: Cast to ObjectId failed for value "x" (type string) at path "_id" (Node.js)CastError ObjectIdfile_type_not_allowed — Upload error: File type not allowed / unsupported file type (API)file_type_not_allowedinvalid_date — API Error: Invalid date format — expected ISO 8601 (YYYY-MM-DDTHH:mm:ssZ) (API)invalid_dateinvalid_request — OAuth 2.0 Error: invalid_request (missing or invalid parameter) (Authentication)invalid_requestinvalid_type — API Error: Invalid type — expected integer, received string (API)invalid_typeinvalid_value — API Error: Invalid parameter value — must be one of the allowed values / out of range (API)invalid_valueinvalid_id

Explore the map of this error Full error map →

🧠 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.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.