Errors & troubleshooting

The error envelope, what each status code means, and the codes you will hit most.

Every error from the Flow Retail API comes back as the same three-field object, whatever the status code:

{
  "code": "ErrPermissionDenied",
  "message": "User does not have permission to access this store",
  "logId": "9f1c2e70-4b8a-4d3e-9a17-2c5b1d0e8f44"
}

Field	Use it for
code	Branching in your code. Stable and machine-readable.
message	Showing a human what went wrong. May be translated — never match on it.
logId	Correlating with our logs. Quote it when you contact support.

Branch on code, never on message. Messages are localised and rewritten; codes are not.

Status codes

Status	Meaning	What to do
400	Malformed request or failed validation	Fix the request. Retrying will not help.
401	Missing, invalid or expired token	Re-authenticate.
403	Valid token, insufficient permission	Grant the permission in Flow Retail Admin.
404	Resource does not exist, or is outside your tenant	Check the Uid and the tenant in the path.
406	Unacceptable content type	Send and accept application/json.
409	Conflict with current state	Re-read the resource and retry.
429	Too many requests	Back off and retry.
500	Unexpected server error	Retry with backoff. Report it with the logId if it persists.
503	Temporarily unavailable	Retry with backoff.

Common error codes

Code	Usually means
ErrBadRequest	The request body or parameters failed validation
ErrNotFound	No such resource, or it belongs to another tenant
ErrInvalidToken	The bearer token is malformed, expired or revoked
ErrAccessDenied	The token is valid but not allowed here
ErrPermissionDenied	The user lacks the permission the endpoint requires
ErrStoreAccessDenied	The user has no access to the store in the path
ErrUserIsNotAdmin	The endpoint requires an admin user
ErrUserIsNotSuperAdmin	The endpoint requires a super admin
ErrInvalidPrimaryKey	A Uid in the path or body is not a valid identifier
ErrDuplicatePrimaryKey	Something with that identifier already exists
ErrInvalidSortBy	The sortBy field is not sortable on this endpoint
ErrInvalidSortDirection	sortDirection was not ASC or DESC
ErrGeneric	An error with no more specific code
ErrInternalServerError	An unhandled failure on our side

A 404 on an endpoint you expect to work is most often a tenant mismatch rather than a missing record — the token and the {tenantUid} in the path have to agree.

A note on the specification

Most operations in the OpenAPI specification document only their success response. That does not mean errors are not returned — the envelope above applies to every endpoint regardless of what the specification lists. Handle the three-field shape for any non-2xx status, rather than trusting the declared response list to be complete.

We are filling these in over time.

Retries and backoff

The API does not publish rate limits. Write your client so that it copes anyway:

• Treat any 429 as a signal to back off and retry after a delay, whether or not you have seen one before.

• Back off on 5xx and 503 with exponential delay and jitter.

• Do not retry 4xx other than 429 — the request will fail the same way every time until you change it.

Keep concurrency modest on bulk work and prefer the batch endpoints where they exist. Large pageSize values on wide collections are the usual cause of timeouts.

Getting help

When something is wrong and the error does not explain it, send us the logId. It lets us find the exact request in our logs, with its root cause, in seconds — far faster than a description of what you were doing.

Email [e-mail]. Every integration partner gets direct access to the developers who build this API.