Skip to Content
FR8 Factory Docs

Errors

What each response code means, and what your sender should do about it.

CodeMeaningWhat to do
202Accepted and durably storedConsider it delivered
400Malformed body, bad timestamp, or too largeDo not retry
401Bad or missing signatureDo not retry — fix the signing
429Rate limitedBack off; we send Retry-After
5xxOur faultRetry with backoff

Why 202 and not 200

We respond as soon as the event is durably stored, before processing it. So 202 means "we have it and will not lose it" — not "the load is in our system".

That is intentional. It keeps your delivery fast, and it decouples your retry behaviour from our processing. If a bug on our side fails to process an event, that is ours to replay, and you should never be redelivering because of it.

What we reject at the door

Before we parse anything, we reject with 400:

  • a body over 16 KB
  • a Content-Type that is not application/json
  • an occurredAt with no zone designator
  • a timestamp outside the five-minute signature window

A misconfigured sender should fail loudly and immediately rather than somewhere deeper in, where the cause is harder to see.

Unrecognised events are accepted, not rejected

An eventType we do not know, or an apiVersion higher than we support, gets 202. We store it, log it, and ignore it.

A 400 there would teach your sender to give up on events we may well want — so it is safe for you to ship a new event type before we support it.

What a 401 costs, and why we still ask you not to retry

We should be straight about this, because the rule has a cost and it mostly lands on us.

A 401 caused by our misconfiguration — a secret mishandled during rotation, say — becomes a permanently lost event under the no-retry rule. We accept that, because retrying a genuinely bad signature forever is the worse failure.

What we owe you in exchange:

  • we alert on any 401 spike and treat it as an incident on our side
  • the catch-up path is how anything lost in that window gets recovered

If you see sustained 401s, that is our bug, not yours. Tell us and stop sending rather than working around it.

Delivery

Retries, idempotency, timeouts, and how to catch up after an outage.

On this page

Why 202 and not 200What we reject at the doorUnrecognised events are accepted, not rejectedWhat a 401 costs, and why we still ask you not to retry
Help

How do I get API access?

API keys are issued per customer by the FR8 Factory team. Ask your account contact — or send us a request through the Help desk tab with your company name and use case.

How do I authenticate requests?

Send your API key in the Authorization header on every request. Keys are secret — never ship them in browser code or mobile apps.

Open the guide — How do I authenticate requests?

How do I keep my copy of the data in sync?

Use delta polling: request only records changed since your last sync cursor instead of re-downloading everything. The guide covers cursors, ordering, and replay safety.

Open the guide — How do I keep my copy of the data in sync?

What are the rate limits?

Limits are per API key and documented on the rate-limits page, along with the response headers that tell you where you stand and how to back off.

Open the guide — What are the rate limits?

What does each load field mean?

The load field dictionary defines every field the API returns — types, nullability, and freight-domain meaning (pick vs drop dates, AR, equipment types).

Open the guide — What does each load field mean?

Found a bug or missing data?

Send it through the Help desk tab with the request you made and what you expected back. You'll get a reference code, and we'll email you when it's resolved.