Errors and idempotency

// Success, every endpoint except /health
{
  "success": true,
  "data": { },          // object or array, endpoint specific
  "meta": { },          // optional: query echo, responseTime, notes
  "pagination": { }     // search endpoints only
}

// Error raised by a route handler
{
  "success": false,
  "error": "Case not found"
}

// Validation error, HTTP 400
{
  "success": false,
  "error": "Validation failed. Please check your request and try again.",
  "details": ["query: Search query cannot be empty. Please provide a search term."]
}

// The auth and rate limit layers answer with a bare object and no success field
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Maximum 10 requests per minute allowed.",
  "retryAfter": 37,
  "resetTime": "2026-08-10T09:41:12.884Z"
}

Two exceptions to check for in client code. First, GET /health returns a flat object with no data key. Second, POST /search/cases/semantic writes its 200 status line before it starts work, in order to hold the connection open through a slow vector search. If that work then fails you receive HTTP 200 with success: false in the body. Branch on the body, not only on the status code.

Every error body on this API has the same shape: { success: false, code, message, error, requestId }. error mirrors message for backward compatibility with older bare { error } bodies. Every response, success or failure, also carries an X-Request-Id header you can hand to support to join a report to a server side log line.

Every response this API sends, success or failure, carries an X-Request-Id header. Failures also echo it in the body, as requestId, alongside the same one error shape used everywhere on this API: { success: false, code, message, error, requestId }. code is the stable machine readable string to branch your error handling on; error mirrors message for backward compatibility with older bare { error } bodies.

Send an Idempotency-Key request header on POST /party/screen, POST /party/screen/batch, POST /cases/:id/analyze, POST /cases/:id/analyze-consolidated or POST /request-timeline and a dropped connection, a client side timeout, or a retry loop can never charge you twice for the same call. The header is 1 to 128 characters of letters, digits, underscore, period or hyphen, scoped to your API key, and honoured for 24 hours from the first call that used it.

• Same key, identical request body: the stored response from the first call is replayed verbatim, with an added Idempotency-Replayed: true header, and nothing is charged a second time.
• Same key, a different request body: refused with HTTP 409 IDEMPOTENCY_KEY_REUSED, so a bug that reuses a key by accident cannot silently serve the wrong stored answer.
• Same key, sent again while the first call is still in flight: refused with HTTP 409 IDEMPOTENCY_IN_PROGRESS rather than doing the work twice concurrently.
• A header that does not match the allowed shape: refused with HTTP 400 IDEMPOTENCY_KEY_INVALID before the request body is even read.
• An error response is never stored against the key: a call that fails is free to retry with the same Idempotency-Key and actually run again.
• The header is optional. Omit it and every call runs independently, exactly as today.

curl -X POST https://research.courtmesh.ai/api/v1/prod/party/screen \
  -H "X-API-Key: cm-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-flow-user-88213-kyc-check" \
  -d '{ "name": "Rambaksh Enterprises", "entityType": "company", "purpose": "kyc" }'