Error codes
The type URI in every error body resolves to an anchor on this page. Branch on code; never string-match detail.
invalid_request
400
not retryable
What it means
A parameter is malformed or missing.
Why it happens
- A required parameter was omitted.
- A value has the wrong type or format.
How to fix it
Check the `field` member for the parameter at fault, fix it, and resend. Do not retry unchanged.
Extensions on this problem type
field, valid_options
unknown_retailer
400
not retryable
What it means
The `retailer` value is not one we recognise.
Why it happens
- The value was guessed rather than taken from a coverage response.
- A typo in an otherwise valid slug.
How to fix it
Call `GET /v1/coverage` to list the retailers available to you, or use one of the suggestions in `valid_options`.
Extensions on this problem type
field, valid_options
unknown_category
400
not retryable
What it means
The `category` value is not recognised for the retailer you queried.
Why it happens
- The value was guessed rather than taken from a coverage response.
- The category exists for a different retailer, but not this one.
How to fix it
Call `GET /v1/coverage?retailer=...` to list that retailer's categories, or use one of the suggestions in `valid_options`.
Extensions on this problem type
field, valid_options
unknown_department
400
not retryable
What it means
The `department` value is not recognised for the retailer you queried.
Why it happens
- The value was guessed rather than taken from a coverage response.
- The department exists for a different retailer, but not this one.
How to fix it
Call `GET /v1/coverage` to list the retailer, category and department combinations available to you, or use one of the suggestions in `valid_options`.
Extensions on this problem type
field, valid_options
invalid_date_range
400
not retryable
What it means
`start_date` is after `end_date`, or a date is malformed.
Why it happens
- Dates are not ISO 8601 (`YYYY-MM-DD`).
- The range is inverted.
How to fix it
Send ISO 8601 dates with `start_date` on or before `end_date`.
Extensions on this problem type
field
invalid_cursor
400
not retryable
What it means
The cursor is expired, malformed, or not one we issued.
Why it happens
- The cursor was stored longer than its lifetime.
- The cursor string was truncated or edited.
How to fix it
Restart the walk from the first page without a `cursor` parameter.
Extensions on this problem type
field
missing_credentials
401
not retryable
What it means
No credential was presented.
Why it happens
- The `Authorization` header is absent or not a Bearer token.
How to fix it
Send `Authorization: Bearer <your API key>`. Create a key in the developer portal; the secret is shown once, at creation.
Extensions on this problem type
none
invalid_credentials
401
not retryable
What it means
The credential is unknown or revoked. Deliberately one answer for both.
Why it happens
- The key was revoked in the console.
- The word `Bearer` was pasted into a field that adds it again.
- The key was truncated in transit or on paste.
How to fix it
Check the key's status in the developer portal. Keys do not expire, so a key that worked before and fails now was revoked - create a new one.
Extensions on this problem type
none
insufficient_scope
403
not retryable
What it means
The credential is valid but your team is not entitled to this endpoint.
Why it happens
- The team's entitlement does not include it.
How to fix it
The `detail` names what is missing. Ask your team admin about the entitlement, or email support@stylumia.com with what you are building.
Extensions on this problem type
none
not_found
404
not retryable
What it means
This endpoint or resource does not exist.
Why it happens
- A typo in the path.
- A resource id outside what your team can see.
How to fix it
Check the path against the API reference. A resource your team cannot see is reported absent, not forbidden.
Extensions on this problem type
none
rate_limited
429
retryable
What it means
The published per-team limit was exceeded.
Why it happens
- Requests were sent faster than the limit for this endpoint group.
How to fix it
Honour the `Retry-After` header, then resume. The `RateLimit-*` headers on every response let a client self-throttle before hitting this.
Extensions on this problem type
none
upstream_timeout
504
retryable
What it means
We were too slow answering, not you. The result is indeterminate.
Why it happens
- A data query exceeded our internal deadline.
How to fix it
Retry with backoff. Reads are safe to repeat - nothing here mutates state.
Extensions on this problem type
none
internal_error
500
retryable
What it means
Something unforeseen failed on our side. The cause is logged with your request id.
Why it happens
- An unhandled error in the service.
How to fix it
Retry once with backoff. If it persists, contact support quoting the `request_id`.
Extensions on this problem type
none