Errors

Failed session API requests return a consistent JSON body. Successful responses return the resource directly (not this envelope).

Error body

{
  "errors": [
    "'On Complete Url' must be an absolute https URL."
  ],
  "code": "VALIDATION_ERROR",
  "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Field	Description
errors	One or more human-readable messages. Use these to correct the request or decide next steps.
code	Optional stable code when Billtrust can give you a clear signal. Omitted on generic failures.
correlationId	Always present. Include this when contacting Billtrust Support.

How to handle failures

Kind of failure	What you see	What to do
Fixable request problem	400 + specific errors[] (often with code)	Correct the request and retry
Missing resource	404 + a short plain message	Check the id, email, or tenant you sent
Not allowed	403 + permission message	Use a user who is allowed to start checkout for this flow
Conflicting account data	409 + account message	Follow the message (for example an inactive account)
Tenant not set up	400 or 424 + SUPPLIER_NOT_CONFIGURED	Contact Billtrust to finish enablement
Unexpected / timeout	500 or 504 + generic message only	Retry with backoff; if it persists, contact support with correlationId

Unexpected failures intentionally look like:

{
  "errors": [
    "An unexpected error occurred."
  ],
  "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

There is no code on that body. Rely on the statuses, messages, and codes documented below—not on hidden internal error text.

HTTP status codes

Status	Meaning	What to do
400 Bad Request	Invalid request fields, or a configuration/business rule you can usually address	Read errors and code; fix and retry
403 Forbidden	The user is known but not allowed to perform this action	Use an appropriate user for the flow
404 Not Found	Session, tenant, or user could not be found	Check inputs; wrong-tenant session ids look the same as unknown
409 Conflict	Data exists in a state that blocks the request	Follow the message (for example an inactive account)
415 Unsupported Media Type	Missing or wrong Content-Type	Send Content-Type: application/json on request bodies
424 Failed Dependency	Tenant is not configured for checkout / ExtendPay	Complete enablement with Billtrust, then retry
500 Internal Server Error	Unexpected failure	Retry; contact support with correlationId if it continues
504 Gateway Timeout	The request timed out waiting on a dependency	Retry; contact support with correlationId if it continues

Error codes (code)

These codes may appear on the session API when applicable:

Code	Typical status	Meaning	What to do	Example message
VALIDATION_ERROR	400	Request failed field validation, or a required payment-policy default is missing	Fix the fields listed in errors[]	Field-level text (for example "'On Complete Url' must be an absolute https URL."), or FFDID or FFDName is required if default FFDID is not set
INVALID_FFD	400	The payment policy (ffdId / ffdName) you sent was not found for the supplier	Correct the policy values, or omit both to use the supplier default	The provided FFD was not found for the supplier.
SUPPLIER_NOT_CONFIGURED	400 or 424	Your tenant is not set up for ExtendPay / checkout	Contact Billtrust to finish enablement, then retry	Supplier is not configured for ExtendPay.

Common outcomes (no code)

Status	Message	When
404	Session not found.	Get session id is unknown for this tenant
404	Tenant not found.	Tenant could not be resolved
404	User not found.	The user email could not be resolved for this flow
403	You do not have permission to perform this action.	User is not allowed to start this checkout
409	Account '{accountNumber}' already exists but is not active.	Buyer account exists but is not active
500 / 504	An unexpected error occurred.	Unexpected failure or timeout

Validation tips (create session)

Problem	Fix
Amount format	Plain decimal strings: "100.00" (no $ or commas)
Date format	ISO 8601 yyyy-MM-dd only
sourceType	One of: supplierPortal, counterSoftware, fieldServiceApp, buyerPortal
onCompleteUrl	Absolute https URL
accountNumber	≤ 50 characters, not -1, no :
Discount fields	Send both amount and date, or neither
Documents	At least one item; at most 250 combined
Duplicate invoices	Each invoiceNumber once per request
Payment policy (FFD)	Omit both ffdId and ffdName for the supplier default; or send a valid id/name

Support

1. Capture correlationId from every error response.
2. Capture extendPaySessionId when you have one (successful creates only).
3. Provide both values to Billtrust Support for investigation.