Reporting API Errors and Troubleshooting

Errors show up in two places: a request can be rejected with an HTTP error, or a queued run can fail before it finishes. Authentication works the same as the rest of the Shippo API. See the Authentication guide.

Error format

When Reporting API rejects a request, you get an RFC 7807 problem document with Content-Type: application/problem+json, except for authentication failures. Problem documents have four fields:

Field	Type	Meaning
`type`	string	An identifier URI ending in the stable error code. It is not a documentation link; match on the last path segment only.
`title`	string	Short human-readable summary.
`status`	integer	HTTP status code.
`detail`	string	Human-readable explanation.

Match on the last segment of type (for example, invalid-column). Treat title and detail as display text. We may change their wording.

A missing or invalid token returns 401 application/json with a detail field.

HTTP errors

Scenario	HTTP	`type` segment	Recovery
Token missing, malformed, or not recognized	`401`	—	Send `Authorization: ShippoToken <token>` on every call and handle the response by status.
A column is not listed in the report type’s `available_columns`	`400`	`invalid-column`	Use `available_columns` `name` values, or omit `columns` for the defaults.
Interval exceeds the 92-day cap, or a column is requested more than once	`400`	`invalid-parameter`	Shrink the interval or remove duplicate columns.
Unknown fields in body, or `interval.end` not greater than `interval.start`	`422`	`validation-error`	Remove undocumented fields. Set `end > start`.
`report_type` key not in active catalog	`404`	`report-type-not-found`	List `/v2/reporting/reports` for valid `{name}.v{version}` keys.
Run id not found	`404`	`run-not-found`	Use the id from a create or list response. An unknown run id returns `404`.
Interval outside the report type’s data window	`404`	`data-unavailable`	Check the report type’s `data_availability` window, then request an interval that falls inside it.
Same `idempotency_key` reused with a different request body	`409`	`idempotency-conflict`	Use a new key for a new request, or resend the exact original body to replay the first run.
Service temporarily unavailable	`503`	`service-unavailable`	Retry with exponential backoff.

Idempotency

idempotency_key is optional. It’s a string you supply, 1 to 128 characters.

No key, or a new unused key: you get 201 Created and a new run with status: QUEUED.
The same key with an identical request body: you get 200 OK and the run that key already created, a safe replay.
The same key with a different request body: you get 409 with the idempotency-conflict type.

Without a key, every create makes a new run. There is no keyless deduplication. Send a key when you want a retry to land on the same run.

Run failures

A run moves from QUEUED to PROCESSING, then to SUCCEEDED or FAILED. When a run fails in the background, you get HTTP 200 with status: FAILED and an error object, not an HTTP error code. A timeout is one kind of FAILED, not a separate state.

A run with status: FAILED is HTTP 200 with status: FAILED, not an HTTP error. Read error.code to handle it.

`error.code`	Meaning	Recovery
`invalid_run_request`	Request was invalid.	Fix the report type, interval, or columns, then create a new run.
`run_timeout`	Exceeded processing time.	Narrow the interval or reduce columns, then create a new run.
`service_unavailable`	Temporarily unavailable.	Wait, then create a new run.
`run_processing_failed`	Data processing failed.	Create a new run.
`run_failed`	Run could not complete.	Create a new run.

To retry any failed run, create a new run. Don’t re-GET the same id.

Example flow

1. Create a run POST /v2/reporting/runs returns 201 Created with status: QUEUED:

cURL

curl -X POST https://api.goshippo.com/v2/reporting/runs \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "invoice.v1",
    "interval": { "start": 1704067200, "end": 1706745600 },
    "columns": ["invoice_number", "invoice_total_amount"],
    "output_format": "csv_gzip"
  }'

To make a retry safe, add an idempotency_key. Resending the same key with the same body returns 200 with the existing run; reusing it with a different body returns 409. 2. Poll Poll GET /v2/reporting/runs/{run_id} until status is terminal (SUCCEEDED or FAILED). If processing time is exceeded, the run has status: FAILED and error.code: run_timeout. 3. Download A SUCCEEDED run includes result.download. The signed URL expires at the result.download.expires timestamp (a UTC epoch second). If download.status is unavailable or the URL has expired, re-GET the run for a fresh one.

cURL

curl -L -o report.csv.gz "https://<download-host>/<opaque-path>?<signature>"

The download request does not require a Shippo Authorization header.

Next steps

Create and poll a report run for the full walkthrough
Authentication for API token setup
API reference: create a run · get a run

Overview

Get started

AI & agents

Guides

Concepts

Error format

HTTP errors

Idempotency

Run failures

Example flow

Next steps

​Error format

​HTTP errors

​Idempotency

​Run failures

​Example flow

​Next steps

Error format

HTTP errors

Idempotency

Run failures

Example flow

Next steps