How Plaidly reports errors today, and the envelope the platform is converging on

Error Model

Live today

Every non-2xx response body is:

{
  "code": 5,
  "message": "idempotency key was already used with a different payload"
}

Field	Type	Present
`code`	integer (`int64`)	always
`message`	string	always

code is a small integer enum, not a machine-readable string slug:

`code`	Meaning
`1`	Internal error
`2`	Not found
`3`	Bad request
`4`	Too many requests (rate limited)
`5`	Conflict (e.g. idempotency key reused with a different payload)
`6`	Client cancelled the request
`7`	Forbidden / auth failure
`8`	Service unavailable

There is no field, remediation, request_id, or retryable in the response body today. Correlate a failed request using the response headers and your own request timestamp/URL when filing a support request.

Planned envelope

The phase-1 agent-first design locks in a richer, additive envelope:

{
  "code": "conflict",
  "message": "idempotency key was already used with a different payload",
  "field": "amount",
  "remediation": "retry with a new Idempotency-Key or the original payload",
  "request_id": "req_01HX9K...",
  "retryable": false
}

Field	Type	Required	Notes
`code`	string	yes	Stable machine-readable slug (e.g. `conflict`, `not_found`) — replaces the current integer `code`
`message`	string	yes	Human-readable description
`field`	string	no	Present when the error is attributable to a single request field
`remediation`	string	no	A short hint on how to resolve the error
`request_id`	string	no	Correlates the error to server-side logs
`retryable`	boolean	no	Whether retrying the exact same request is expected to succeed

message and code remain the only fields you can depend on being present; everything else is additive. Agents and SDKs should treat unknown fields as ignorable rather than failing to parse.

Until this ships, do not write client code that assumes code is a string or that field/remediation/request_id/retryable exist — check for their presence defensively if you want to be ready early.

Idempotency — the 409 conflict case above is the most common source of the code: 5 error today
Register a merchant

Error Model

Error Model

Live today

Planned envelope

Related

On this page