Skip to main content
Every Perform.AI API response is JSON. Alongside the HTTP status code, the response body carries an api_response code that tells you precisely what happened — including cases HTTP alone can’t express, such as a success with warnings.

​
The response envelope

Every functional endpoint returns an api_response field. On success its value is the string "200", usually accompanied by a data object or array:
The shape of data varies by endpoint: an object (Create Shipment, Retrieve Shipment Details), an array (List Shipments), or absent entirely when there is nothing to return (Create Events).
The one exception is the token endpoint: its success response contains no api_response field — only access_token, expires_in, and token_type.
In application responses api_response is a string ("200", "299", "4030"). Errors generated at the API gateway — authorization failures and throttling — return it as a number (403, 429). Parse it leniently: treat "403" and 403 as the same code.

​
Success with warnings (299)

A request can succeed while parts of it could not be applied — a value in the wrong format, or a reference that isn’t configured in your account. The request still processes, and the response tells you what was skipped: HTTP status 299, api_response: "299", and a warnings object mapping each affected field to an array of messages.
Warnings you can encounter across endpoints:
Treat HTTP 299 as a signal to inspect, not to retry. The resource was created or updated — resending the same request creates duplicates, not fixes.
Endpoint-specific warnings are listed on each endpoint’s reference page.

​
Request-level errors

These apply across all endpoints and relate to the request as a whole:
A 4041 “no results” response is an empty search result, not a failure — handle it as “zero shipments matched”. Endpoints that list documents, labels, PUDO locations, or carrier configurations instead return HTTP 200 with an empty data array.

​
Field validation errors (4030)

When one or more fields fail validation, the response is HTTP 400 with api_response: "4030" and an errors object mapping each rejected field to its messages:
For fields inside arrays — line items, events, shipping costs — errors are keyed by the item’s position in the array (as a string), then the field inside it:
Nothing is persisted when a request fails validation: fix the listed fields and resend the whole request. Each endpoint’s reference page lists its specific validation rules and messages.