Get started
Errors
Errors return a non-2xx status and a JSON body with a stable code and a readable message.
v2
A v2 error carries error.code and error.message. A 400 adds issues, one entry per invalid input with its path. Branch on error.code, not on the message.
json
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid input",
"issues": [{ "code": "invalid_type", "message": "Expected string", "path": ["legalName"] }]
}
}| Status | Schema | Meaning |
|---|---|---|
| 400 | error.BAD_REQUEST | Invalid input data |
| 401 | error.UNAUTHORIZED | Authorization not provided |
| 402 | error.PAYMENT_REQUIRED | Not enough credits |
| 403 | error.FORBIDDEN | Insufficient access |
| 404 | error.NOT_FOUND | Not found |
| 409 | error.CONFLICT | The first request with this Idempotency-Key is still filing |
| 412 | error.PRECONDITION_FAILED | No webhook URL for the key's environment |
| 413 | error.PAYLOAD_TOO_LARGE | The file or the row count is over the limit |
| 422 | error.UNPROCESSABLE_CONTENT | The entry is not valid |
| 500 | error.INTERNAL_SERVER_ERROR | Internal server error |
| 501 | error.NOT_IMPLEMENTED | `config: "post"` is not available yet |
| 502 | error.BAD_GATEWAY | Submitting to CBP failed |
v1 (deprecated)
Branch on error.code, not on the message. Validation errors add a details array with one entry per problem.
json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": ["rates[0].origin must be a 2-letter ISO country code"]
}
}v1 codes
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_ERROR | The body failed validation. `details` lists every problem. |
| 401 | MISSING_API_KEY | No X-API-Key header. |
| 401 | INVALID_API_KEY_FORMAT | The key does not start with tflo_. |
| 401 | INVALID_API_KEY | The key is unknown, revoked or wrong. |
| 401 | EXPIRED_API_KEY | The key has passed its expiry date. |
| 402 | INSUFFICIENT_CREDITS | The balance cannot cover the request. `needed`, `available` and `purchaseUrl` say what to add; a `runId` means the run exists and resumes once credits land. |
| 403 | INSUFFICIENT_PERMISSIONS | The key lacks a scope the endpoint requires. `details` lists both. |
| 404 | NOT_FOUND | No job with this id exists in your organization. |
| 429 | RATE_LIMIT_EXCEEDED / DAILY_RATE_LIMIT_EXCEEDED | Too many requests. Wait `retryAfter` seconds. |
| 500 | INTERNAL_SERVER_ERROR | Something failed on our side. Retry with backoff. |
Failed jobs
A v1 job that was accepted and then failed does not change the HTTP status of the poll. GET on the job returns 200 with "status": "failed" and an error object.