Errors

The API uses conventional HTTP status codes and returns a JSON error body. There are three error shapes.

Error shapes

Validation errors (400) return an error string plus a details array, one entry per invalid field:

{
  "error": "Validation failed",
  "details": [
    { "field": "clientId", "message": "Invalid client ID format" },
    { "field": "firstName", "message": "First name is required" }
  ]
}

Most other errors return an error label and a human-readable message:

{
  "error": "Unauthorized",
  "message": "Invalid organization authentication token"
}

An unmatched route (404) returns just an error label, with no message:

{
  "error": "Not Found"
}

Status codes

Status	`error` label	When it happens
`400`	`Validation failed` / `Bad Request`	Request body, params or query failed schema validation; malformed or expired token on revoke; missing `X-Idempotency-Key` on a mutating request.
`401`	`Unauthorized`	Missing/invalid/expired/revoked token, missing `x-client-id`, `x-client-id` ≠ token, invalid credentials, no signing key registered, or failed signature / Content-Digest verification.
`403`	`Forbidden`	Client IP is not in the credential’s allowlist (`trustedIps`).
`404`	`Not found` / `Transaction not found` / `Not Found`	The resource does not exist or does not belong to your organization. An unmatched route returns `{ "error": "Not Found" }` with no `message`.
`409`	`Conflict`	A concurrent request with the same `X-Idempotency-Key` is still in flight. Retry once it settles.
`422`	`Unprocessable Entity`	An `X-Idempotency-Key` was reused with a different request payload.
`500`	`Internal Server Error`	Unexpected server error. Safe to retry idempotent requests with backoff.

Common examples

Missing x-client-id header (401)

{
  "error": "Unauthorized",
  "message": "x-client-id header is required"
}

x-client-id does not match the token (401)

{
  "error": "Unauthorized",
  "message": "Client ID mismatch"
}

Client IP not allowlisted (403)

{
  "error": "Forbidden",
  "message": "Client IP not allowed"
}

Request not signed, or signature does not verify (401)

{
  "error": "Unauthorized",
  "message": "Signature verification failed"
}

Returned when Signature / Signature-Input are missing, malformed, expired, cover a component the request does not carry, or do not verify against your registered key.

Body does not match the digest (401)

{
  "error": "Unauthorized",
  "message": "Content-Digest verification failed"
}

No public key registered for your credential (401)

{
  "error": "Unauthorized",
  "message": "No signing key registered for this client"
}

You cannot fix this one by re-signing — your credential has no public key on file. Contact engineering.support@pipevest.com to register or rotate it.

Missing idempotency key on a mutation (400)

{
  "error": "Bad Request",
  "message": "X-Idempotency-Key header is required for this request"
}