Errors and retries

Errors use RFC 9457 application/problem+json. Parse the HTTP status, problem type, and field-level error code; do not depend on human-readable wording.

{
  "type": "https://docs.paypathiq.com/problems/dependency_missing",
  "title": "Receivable dependency missing",
  "status": 409,
  "detail": "The referenced Receivable does not exist in this Integration and Client scope.",
  "requestId": "29400000-0000-4000-8000-000000000001"
}

A 422 validation_error also has an errors array; see field error codes. Each problem type links to a page that explains the error. The error index lists every problem type.

Error index

Every problem type is https://docs.paypathiq.com/problems/<name>. Retryable means the same request can succeed later without changes. After the cause is fixed means you must fix something first, then send the request again.

Type	Status	Retryable	Meaning
`malformed_json`	400	No	PayPathIQ could not parse the request body.
`invalid_api_key`	401	No	PayPathIQ could not authenticate the request.
`client_scope_denied`	403	No	The key is valid, but its grant does not allow this request.
`batch_not_found`	404	No	No batch with this `externalBatchId` exists for your connection and Client.
`customer_not_found`	404	No	No Customer exists at this URL for your Integration and Client.
`financial_event_not_found`	404	No	No financial evidence exists for this identity within your Client and Source scope.
`payment_observation_not_found`	404	No	No Payment observation exists at this URL for your Integration and Client.
`payment_request_not_found`	404	No	No payment request exists at this identifier within your Client.
`receivable_not_found`	404	No	No Receivable exists at this URL for your Integration and Client.
`recovery_instruction_not_found`	404	No	No recovery instruction exists at this URL for your Integration and Client.
`route_not_found`	404	No	No API route exists at this path.
`webhook_endpoint_not_found`	404	No	You read, rotated or disabled the webhook endpoint of a Client that has none.
`method_not_allowed`	405	No	The path exists, but it does not support the HTTP method you sent.
`allocation_exceeds_balance`	409	No	A Payment observation allocates more money to a Receivable than that Receivable currently owes.
`balance_mismatch`	409	No	A balance guard or balance bound in your request does not fit the Receivable’s balance at the moment PayPathIQ processed it.
`batch_conflict`	409	No	You reused an `externalBatchId` with a different body.
`book_completion_unverified`	409	After the cause is fixed	PayPathIQ could not verify that the listed batches carry the complete book (the full set of Receivables in the Source).
`contact_update_unsupported`	409	No	You tried to change a Customer’s `contacts`, but PayPathIQ cannot tell which Contact is which.
`dependency_missing`	409	After the cause is fixed	The request refers to a record that does not exist yet for your Integration and Client.
`financial_event_conflict`	409	No	You reused an identity for financial evidence that was already accepted with different content.
`financial_operation_required`	409	No	The operation you used cannot change money or the obligation type in the current mode.
`invalid_receivable_transition`	409	No	The lifecycle command is not allowed from the Receivable’s current status.
`pause_not_active`	409	No	You sent `clear-pause` for a Receivable that is not paused.
`payment_attempt_in_progress`	409	After the cause is fixed	A payment attempt is already running for one of the Receivables in your hosted payment request.
`payment_merchant_unconfigured`	409	No	The Client is not set up to take hosted payments in this environment.
`payment_not_confirmed`	409	After the cause is fixed	You sent receipt lines for money that the payment provider has not confirmed, or that PayPathIQ cannot match safely.
`payment_observation_conflict`	409	No	A Payment observation conflicts with one already accepted.
`payment_policy_blocked`	409	No	PayPathIQ’s current Customer and Receivable policy does not allow this external Payment to be recorded.
`payment_request_conflict`	409	No	You reused a payment request identity with a different Customer, Receivable or amount.
`payment_request_held`	409	After the cause is fixed	PayPathIQ is holding new payment initiation for these Receivables.
`payment_request_not_payable`	409	No	One or more Receivables or the Customer cannot be paid through a hosted request right now.
`payment_request_stale`	409	No	A requested amount no longer equals the Receivable’s current working balance, so the request would charge the wrong amount.
`payment_request_unsupported`	409	No	Hosted payment requests are not available on this connection.
`positive_recoverable_amount_required`	409	After the cause is fixed	You tried to reopen a Receivable whose `recoverableAmount` is zero.
`receipt_delivery_changed`	409	No	The receipt content no longer matches the delivery reference.
`receipt_delivery_outcome_ambiguous`	409	After the cause is fixed	A previous delivery attempt ended with an unknown outcome, such as a timeout after the request was sent.
`receipt_delivery_owned_by_partner`	409	After the cause is fixed	You asked PayPathIQ to deliver a receipt on a connection where the partner owns delivery.
`receipt_delivery_owner_mismatch`	409	No	You used a partner delivery operation on a connection where PayPathIQ owns receipt delivery.
`receipt_delivery_route_unsupported`	409	No	The connection declares PayPathIQ as receipt delivery owner, but no verified vendor route is enabled.
`receivable_state_conflict`	409	No	The request conflicts with the Receivable’s current state.
`reconciliation_resolution_invalid`	409	After the cause is fixed	The resolution you chose does not fit the reconciliation’s state.
`recovery_instruction_conflict`	409	No	One recovery instruction governs one Receivable, and your request breaks that rule.
`recovery_mode_mismatch`	409	No	You sent a recovery instruction to a connection that uses Client-approved rules instead.
`recovery_restriction_active`	409	No	The Source is holding the Receivable, so recovery cannot be authorized yet.
`source_position_conflict`	409	No	A balance snapshot or complete-book declaration is not newer than the evidence PayPathIQ already accepted.
`source_revision_conflict`	409	No	A changed record reused an accepted or older `sourceRevision`.
`change_cursor_expired`	410	No	Your stored cursor points before the oldest retained change, so PayPathIQ cannot replay what you missed.
`request_too_large`	413	No	The request body is larger than 256 KiB.
`unsupported_media_type`	415	No	The `Content-Type` does not match the operation, or the body is compressed.
`invalid_change_cursor`	422	No	The `cursor` is not one this change feed issued for this Integration and Client.
`profile_mismatch`	422	No	The Receivable’s financial type or industry context does not match the profile PayPathIQ set for your connection.
`validation_error`	422	No	A route parameter, query parameter or the request body failed validation.
`webhook_destination_unsafe`	422	No	The `url` of `PUT /v1/clients/{clientCode}/webhook-endpoint` cannot safely receive notifications.
`batch_limit_exceeded`	429	Yes	Your connection already has the maximum number of batches queued or running.
`rate_limit_exceeded`	429	Yes	The request exceeded a rate or concurrency limit.
`projection_unavailable`	503	Yes	An unexpected error stopped PayPathIQ from completing the request safely.

Status codes

Status	Meaning	Action
`400`	Malformed JSON	Correct the request body
`401`	Invalid, revoked, or wrong-environment key	Replace or rotate the key
`403`	Client, scope, or IP allowlist denied	Ask an administrator to verify the grant
`404`	Authorized resource not found, or no route at this path	Verify the external ID and the path
`405`	The path does not support this method	Use a method from the `Allow` header
`409`	Dependency, state, or immutable-event conflict	Reconcile source state
`410`	A change cursor is older than the retained changes	Resynchronize from `from=latest`
`413`	Request body larger than 256 KiB	Send one smaller record
`415`	Wrong `Content-Type` or compressed body	Send uncompressed `application/json`, or `application/merge-patch+json` for `PATCH`
`422`	Route parameter, field, or safety validation failed	Correct the supplied record
`429`	Rate or concurrency limit	Retry after `Retry-After` seconds
`503`	Unexpected failure; nothing was saved	Retry with backoff

Route parameters are validated before the API key. A request with an invalid clientCode or external ID returns 422 even if its key is also invalid.

Retry policy

Retry only 429 and 503 responses. Use exponential backoff with jitter and honor Retry-After when present. Do not retry an unchanged 4xx request other than 429. An edge or network failure without a problem body can also be retried with backoff. Choose the next action by operation, especially when a timeout leaves the outcome unknown:

Operation	After a lost response
Customer `PUT`	Repeat the identical payload before sending a newer update for that Customer
Payment observation `PUT`	Repeat the identical payload with the same observation ID; never generate a new ID for a retry
Receivable descriptive `PUT` or `PATCH`	`GET` the Receivable and reconcile its current balance before resending
Lifecycle command	`GET` the Receivable and check its status before deciding whether another command is needed

Changed descriptions require a newer sourceRevision. Stale or conflicting revisions return 409 source_revision_conflict; balance/type replacement returns 409 financial_operation_required. An old representation cannot restore paid debt. Read and reconcile the current record before choosing the next operation.

See the worked reconciliation example.

Rate limits

Every request counts, including GET.

Limit	Per API key	Per Client (sandbox only)	`Retry-After`
Requests in flight	1	1	`1`
Requests per minute	60	60	`60`

In sandbox, the per-Client limits apply across every key granted for that Client, so two keys for the same Client share one budget. Over a limit, the API returns 429 rate_limit_exceeded. Send requests for one key one at a time, and wait for each response before sending the next.

Field error codes

A 422 validation_error lists up to 20 problems in errors. Each has a JSON pointer to the field and one of these codes:

Code	Meaning
`invalid_type`	The value has the wrong JSON type, or a required field is missing
`invalid_format`	The value does not match the required format, such as a date, timestamp, email address, or ID pattern
`invalid_value`	The value is not one of the allowed values
`too_small`, `too_big`	A string, number, or array is outside its allowed size
`unrecognized_keys`	The object contains a field the contract does not define
`invalid_union`	The object matches none of the allowed shapes. A Customer returns this at the root pointer when `type` is missing or unknown, or when a field inside it, such as a safety assertion `type`, is invalid; check the whole representation
`custom`	A rule across fields failed, such as a duplicate safety assertion type
`sensitive_external_id`	An external ID in the path or body looks like sensitive data
`sensitive_source_reference`	A `sourceReference` looks like sensitive data
`unsupported_client_type`	The Client is a property management Client, which uses the Owners workspace. The `credit_union.v1` profile does not accept its Customers, Receivables, or Payment observations. The `pointer` is empty because the whole request is refused

External IDs use 1–128 characters from A-Z, a-z, 0-9, _, and -. This applies to IDs in the path (clientCode, externalCustomerId, externalReceivableId, externalPaymentObservationId) and in the body (externalContactId, responsibleCustomers[].externalCustomerId, and a Payment observation’s externalReceivableId and relatedExternalPaymentObservationId). They are rejected with sensitive_external_id if they look like an email address, an IBAN, an Irish PPS number, or a PayPathIQ API key, or if they contain only digits after removing - and _. sourceReference values (up to 200 characters) are rejected with sensitive_source_reference if they look like an email address, an IBAN, an Irish PPS number, a PayPathIQ API key, or a payment card number. Use opaque IDs from your integration mapping, not member, loan, or account numbers.

Request IDs and support

Every API response includes X-Request-Id, and every problem body repeats it as requestId. This includes 404 route_not_found for a path that does not exist and 405 method_not_allowed for a method a path does not support. Edge-protection 403 responses do not (see below). If the response has a request ID, include it when you report a failed request to help@paypathiq.com. Do not send the API key or a full personal-data payload.

Edge protection

Before authentication, the edge also rate-limits requests by source address. Those responses are HTTP 403 with no application/problem+json body and no X-Request-Id. Treat a 403 without a problem body as transient: pause that source, wait at least 60 seconds, and retry with backoff. An application 403 problem is a denied grant or scope and is not retryable.

Getting started

Integration guides

Reliability and sync

Going live

Error reference

Error index

Status codes

Retry policy

Rate limits

Field error codes

Request IDs and support

Edge protection

​Error index

​Status codes

​Retry policy

​Rate limits

​Field error codes

​Request IDs and support

​Edge protection

Error index

Status codes

Retry policy

Rate limits

Field error codes

Request IDs and support

Edge protection