Errors and Statuses
Handle API errors, asynchronous job statuses, and retryable responses.
Errors use a consistent JSON shape.
{
"code": "invalid_request",
"message": "Only PDF files are supported."
}Use code for programmatic handling. Use message for logs or user-facing support context.
Common HTTP Status Codes
400 means the request is invalid.
401 means the API key is missing or invalid.
402 means billing is not active for API usage.
403 means API access is disabled or the key does not have the required scope.
404 means the requested resource was not found for this organization.
409 means the request conflicts with the current resource state, such as trying to match from a parsing job that is not completed.
429 means the rate limit was exceeded.
Common Error Codes
invalid_request: request body, files, or parameters are invalid.
invalid_api_key: API key is missing, malformed, or no longer valid.
billing_inactive: billing status does not allow API usage.
forbidden: API access is not enabled or the key does not have access to the endpoint.
not_found: resource does not exist or does not belong to the organization.
conflict: resource is not in the right state for the requested action.
rate_limit_exceeded: too many requests were sent in a short period.
processing_failed: asynchronous processing failed.
matching_failed: TrueSight matching failed.
Job Statuses
InFlow parsing and TrueSight matching are asynchronous.
Common statuses:
queuedprocessingcompletedfailedsupersededfor InFlow parsing only
superseded is terminal and means a newer processing run replaced the InFlow job. It does not produce an inflow.parsing.completed or inflow.parsing.failed webhook.
An InFlow job remains processing until every submitted PDF reaches a terminal result. Terminal failed or unreconciled statements are returned in parsing_details for review rather than being silently omitted.
Do not assume a job is complete immediately after a 202 response. Poll the GET endpoint or use webhooks.
Retry Guidance
Retry network errors and 429 responses with exponential backoff.
Do not retry invalid requests until the request data is fixed.
If a job fails, read the error object in the GET response. You can also use dashboard visibility for support and operations review.
Updated 8 days ago