Errors, limits and support
The shape
{ "error": { "code": "insufficient_stock", "message": "Only 4,000 gold left on this listing", "requestId": "…" } }Switch on the code; show the message to a person; quote the request id to support. Validation refusals add details with the fields that failed.
Codes you will meet
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_price | A price finer than its currency carries (a USD price has two decimal places), or one that is not above zero. On a sheet it lands on the line, as invalid. |
| 401 | unauthenticated | No key, or one that does not exist here. Check the prefix against the host. |
| 401 | key_revoked, key_expired | The key is over. Mint another. |
| 401 | signature_required, signature_invalid, signature_expired, signature_replayed | The key is set to signed requests and this one did not pass. See Signing. |
| 403 | insufficient_scope | The key lacks the route's scope; the body names it. |
| 403 | ip_not_allowed | The key has an address allowlist and this address is not on it. |
| 403 | account_suspended | Reads work; writes that start something do not. |
| 404 | not_found, unknown_game, unknown_server, unknown_package | The id or slug is not ours, or not yours. |
| 409 | external_id_taken | Another of your listings already carries that external id. |
| 409 | placement_locked | A listing cannot move to another game, lane or realm. Make a new line. |
| 409 | illegal_transition | The order is not in a state that allows the move; its state is in the body. |
| 409 | tiers_conflict | A price or minimum change left the volume ladder no longer descending. Send the ladder with it. |
| 422 | idempotency_key_reused | The same key on a different request. |
| 429 | rate_limited | The minute's budget is spent. Wait for Retry-After. |
Versioning
The document carries a date as its version. Fields are added, never removed or renamed, and a new event type is a new subscription, never a change to an existing body. Anything that would break a client gets a new path prefix and a year's notice on the old one.
Support
support@freeport.gg, with the request id. The delivery log in Integrations shows every webhook attempt with our answer and yours; the console's stock sync page shows every failed line with its code. Most questions are answered there before the email is written.