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

**Code:** `invalid_id` · **Category:** API · **Seen on:** REST API

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.

## 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"?

---
Source: [WhatIsMyError](https://whatismyerror.com/errors/api/invalid-identifier-format)
