API error codes

Every error from the Flume Partner API is JSON in one envelope, with a stable code. This page lists every code, its HTTP status, what it means and how to fix it.

The error envelope

{
  "error": {
    "code": "SKU_NOT_IN_SEARCH",
    "message": "This product was not a result of that search. Use the search_session_uuid of the search (or the page) that returned it.",
    "field": "sku_uuid",
    "request_id": "e19b8889-a63b-4000-9dbe-ffd5b9157bd5"
  }
}

Field	Type	Notes
code	string	Stable. Branch on it
message	string	For a person. It can change
field	string or null	The request field at fault, as a dotted path
request_id	string	Quote it to Flume support. Also in the X-Request-Id header
details	object	Sometimes present, with more about a refusal

All codes

Code	Status
PARTNER_KEY_INVALID	401
EMBED_TOKEN_INVALID	401
USER_TOKEN_INVALID	401
USER_NOT_CONNECTED	403
USER_ACCOUNT_CLOSED	403
CONNECT_CODE_INVALID	401
VERIFICATION_CODE_INVALID	422
VERIFICATION_TRIES_EXHAUSTED	422
VERIFICATION_CODE_EXPIRED	422
VERIFICATION_RATE_LIMITED	429
VERIFICATION_EMAIL_FAILED	502
VALIDATION_FAILED	422
NOT_FOUND	404
SESSION_NOT_FOUND	404
SKU_NOT_IN_SEARCH	422
IMAGE_REQUIRED	400
IMAGE_TOO_LARGE	413
IMAGE_UNSUPPORTED	422
SEARCH_UNAVAILABLE	503
BELOW_MINIMUM_ORDER	400
NOT_INSTANTLY_QUOTABLE	400
QUOTE_NOT_READY	422
IDEMPOTENCY_KEY_REQUIRED	400
IDEMPOTENCY_KEY_REUSED	422
IDEMPOTENCY_IN_PROGRESS	409
KEY_LIMIT_REACHED	409
KEY_ROTATION_RATE_LIMITED	429
LAST_ACTIVE_KEY	409
RATE_LIMITED	429
DAILY_LIMIT_REACHED	429
INTERNAL	500

Responses outside the envelope

Response	When
403 with no JSON body	On live, a request from an unsupported country. See Environments
429 with no JSON body and no Retry-After	On live, a network-level limit per IP address. Back off and retry
No response	A network timeout. Retry a write with the same Idempotency-Key

Credentials

PARTNER_KEY_INVALID

• Status: 401.
• Returned by: Every call.
• Meaning: The partner key is missing, unknown, revoked, expired, or from the other environment. On live, also a platform Flume has not enabled yet.
• Fix: Check the header name X-Flume-Partner-Key and the environment. Rotate the key if it was revoked.

EMBED_TOKEN_INVALID

• Status: 401.
• Returned by: Every call.
• Meaning: You sent an Authorization header and no X-Flume-Partner-Key. Flume read the call as one from its own iframe.
• Fix: Send the partner key in X-Flume-Partner-Key. Never send it in Authorization.

USER_TOKEN_INVALID

• Status: 401.
• Returned by: Calls that read X-Flume-User-Token.
• Meaning: The user access token is unknown, revoked, another partner's, or replaced by a later verification. A verification in the iframe replaces it too.
• Fix: Delete the stored token. Exchange the connect code if you have one. Otherwise verify the user again.

USER_NOT_CONNECTED

• Status: 403.
• Returned by: Calls made for a user.
• Meaning: No X-Flume-User-Token header was sent.
• Fix: Send the user's access token. If you hold none, verify the user first.

USER_ACCOUNT_CLOSED

• Status: 403 on calls made for a user. 422 with field: email from the verification calls.
• Returned by: Calls made for a user, and the two verification calls.
• Meaning: The user's email belongs to a Flume account that Flume has closed.
• Fix: Do not retry. The user contacts Flume.

CONNECT_CODE_INVALID

• Status: 401.
• Returned by: POST /users/exchange-connect-code.
• Meaning: The connect code is used, older than 120 seconds, unknown, or another partner's.
• Fix: Exchange each code once, at once. The user verifies again on the next open.

Verification

VERIFICATION_CODE_INVALID

• Status: 422.
• Returned by: POST /users/confirm-verification.
• Meaning: The code is wrong. The message says how many tries are left.
• Fix: Let the user type it again.

VERIFICATION_TRIES_EXHAUSTED

• Status: 422.
• Returned by: POST /users/confirm-verification.
• Meaning: The code was wrong 3 times. It is burned.
• Fix: Send a new code.

VERIFICATION_CODE_EXPIRED

• Status: 422.
• Returned by: POST /users/confirm-verification.
• Meaning: No code is valid: it is older than 10 minutes, already used, or was never sent.
• Fix: Send a new code.

VERIFICATION_RATE_LIMITED

• Status: 429, with Retry-After.
• Returned by: POST /users/trigger-verification.
• Meaning: A resend came too soon, or the mailbox reached its limit. When you send X-Flume-Client-IP, the limit per IP address applies too.
• Fix: Wait Retry-After seconds.

VERIFICATION_EMAIL_FAILED

• Status: 502.
• Returned by: POST /users/trigger-verification.
• Meaning: The email could not be sent.
• Fix: Retry with backoff.

Requests

VALIDATION_FAILED

• Status: 422. 400 for an Idempotency-Key over 255 characters. 405 for a wrong HTTP method.
• Returned by: Every call.
• Meaning: A field is missing, unknown or has an unusable value. field names it as a dotted path. Some refusals carry the detail in details and leave field empty.
• Fix: Fix the field. Request bodies are strict: remove fields the API does not list.

NOT_FOUND

• Status: 404.
• Returned by: Calls that name a product, quote, key, save or user. Also any unknown path.
• Meaning: The thing does not exist, or is not this user's. A search id that is not a UUID also returns this code.
• Fix: Check the id and that it belongs to this user.

SESSION_NOT_FOUND

• Status: 404.
• Returned by: Calls that take search_session_uuid.
• Meaning: The search does not exist, or is another user's.
• Fix: Use a search_session_uuid from one of this user's searches.

SKU_NOT_IN_SEARCH

• Status: 422.
• Returned by: POST /request-instant-quote, POST /save-item, POST /deep-links, POST /sales-requests.
• Meaning: The product was not a result of the search you named.
• Fix: Use the search_session_uuid of the search, or the page, that returned the product.

Search

IMAGE_REQUIRED

• Status: 400.
• Returned by: POST /search.
• Meaning: The request has no image part, or the part is empty.
• Fix: Send the photo as the image part of multipart/form-data. On a retry, read the file again.

IMAGE_TOO_LARGE

• Status: 413.
• Returned by: POST /search.
• Meaning: The photo is over 6,000,000 bytes.
• Fix: Resize or compress the photo.

IMAGE_UNSUPPORTED

• Status: 422.
• Returned by: POST /search.
• Meaning: The file is not a JPEG, PNG or WebP, or it is over 50 megapixels. Flume reads the bytes, not the file name.
• Fix: Convert or resize the photo.

SEARCH_UNAVAILABLE

• Status: 503.
• Returned by: POST /search.
• Meaning: Search is briefly unavailable. The call is not counted against your limit.
• Fix: Retry with backoff.

Quotes and saves

BELOW_MINIMUM_ORDER

• Status: 400.
• Returned by: POST /request-instant-quote.
• Meaning: The quantity is under the product's minimum order. The message states the minimum.
• Fix: Raise quantity_sqft. Read minimum_order_sqft on the product's shipping options.

NOT_INSTANTLY_QUOTABLE

• Status: 400.
• Returned by: POST /request-instant-quote.
• Meaning: Flume's sales team prices this product. There is no instant quote.
• Fix: Check price_on_request first. File a sales request.

QUOTE_NOT_READY

• Status: 422.
• Returned by: POST /save-item, POST /deep-links.
• Meaning: The quote is not READY. On POST /save-item it also covers a quote that expired, is not this user's, lacks the option you named, or is under that option's minimum order.
• Fix: Request a new quote, then try again.

Idempotency

IDEMPOTENCY_KEY_REQUIRED

• Status: 400.
• Returned by: POST /request-instant-quote, POST /keys.
• Meaning: The Idempotency-Key header is missing.
• Fix: Send one key per user action.

IDEMPOTENCY_KEY_REUSED

• Status: 422.
• Returned by: Calls that take Idempotency-Key.
• Meaning: The key was already used with a different body.
• Fix: Use a new key for a new request.

IDEMPOTENCY_IN_PROGRESS

• Status: 409, usually with Retry-After: 2.
• Returned by: Calls that take Idempotency-Key.
• Meaning: The first call with this key is still running.
• Fix: Wait 2 seconds. Retry with the same key.

Keys

KEY_LIMIT_REACHED

• Status: 409.
• Returned by: POST /keys.
• Meaning: You already hold the maximum number of active keys.
• Fix: Revoke a key you no longer use.

KEY_ROTATION_RATE_LIMITED

• Status: 429, with Retry-After: 86400.
• Returned by: POST /keys.
• Meaning: You reached the number of keys you can issue in 24 hours. Your current key keeps working.
• Fix: Wait, then rotate. For a leaked key on live, contact Flume.

LAST_ACTIVE_KEY

• Status: 409.
• Returned by: DELETE /keys/{key_id}.
• Meaning: This is your only working key.
• Fix: Issue a replacement first.

Limits and server

RATE_LIMITED

• Status: 429, with Retry-After.
• Returned by: Calls with a daily limit.
• Meaning: Today's limit for this call is used up. Retry-After is the number of seconds until 00:00 UTC.
• Fix: Stop that call until then. See Limits.

DAILY_LIMIT_REACHED

• Status: 429, with Retry-After.
• Returned by: POST /search, POST /request-instant-quote.
• Meaning: This user's own daily limit of searches or instant quotes is used up. Flume sets this limit per partner account, and it is off by default. details holds kind, limit, reset_at and retry_after_s.
• Fix: Tell the user when they can try again, from details.reset_at. Other users are not affected. See Limits.

INTERNAL

• Status: 500.
• Returned by: Every call.
• Meaning: Something failed on Flume's side.
• Fix: Retry with backoff. Keep the same Idempotency-Key. Send request_id to Flume if it persists.

What is not an error

• POST /request-instant-quote returns 200 with status: FAILED when it could not price. Read failure_reason. See Get an instant quote.
• POST /detect-category returns 200 for every verdict, including error.

See also

• Handle errors: what to retry
• Limits