Errors

All error responses share the same envelope (see Conventions):

{
  "_errors": [
    { "code": "...", "detail": "...", "source": { "parameter": "..." } }
  ]
}

source.parameter is present only on validation errors and points at the request field that failed.

Catalogue

400 — Bad Request

code	Meaning	What to do
CLIENT_ID_HEADER_MISSING	The x-e1-client-id header was not sent.	Add the header to every request. See Authentication.
Validation error (various codes, e.g. INVALID_PARAMETER)	A path parameter was malformed. source.parameter identifies the field.	Fix the offending parameter; the field name is in source.parameter.

401 — Unauthorised

code / detail	Likely cause	What to do
CLIENT_ID_HEADER_MISMATCH	The x-e1-client-id header value does not match the client_id inside the bearer token.	Ensure the header matches the credential you used at the token endpoint.
Unauthorised (plain body)	The bearer token is invalid or expired.	Request a new token. See Authentication.
Unauthorised (plain body)	The companyId in the URL is not registered against your application.	Contact E1 support to add the registration.
Unauthorised (plain body)	The permission on your registration is not published.	Contact E1 support — this is a provisioning issue on our side.
Unauthorised (plain body)	The token’s scopes, intersected with your permission’s scopes, don’t include the scope the route requires.	Request your token with the required scope, or ask support to add it to your permission. For the Supplier API you need speci-finder/read.

Note

The API deliberately returns 401 Unauthorised with a generic body for most authorization failures rather than exposing the specific cause. If you are repeatedly seeing 401 and the token itself is valid, work through the checklist above in order and contact support if you cannot resolve it.

403 — Forbidden

code / detail	Likely cause	What to do
403 / Access denied	The supplier company you are calling for does not hold the required E1 licence for this endpoint (the Supplier API requires the Supplier Professional Plus licence or an equivalent regional variant).	Confirm with the customer that their E1 licence covers Speci-finder access. Contact E1 support if you believe the licence is in place but the call is still rejected.

Note

For upstream-authorisation failures (the case above) the External API forwards the E1 platform’s _errors body verbatim, so the exact detail text may vary. The status code is the stable signal — treat any 403 on the Supplier API as “this customer is not entitled to call this endpoint”.

429 — Too Many Requests

code	Meaning	What to do
(WAF response, no JSON body guaranteed)	Your (bearer token, x-e1-client-id) bucket has exceeded 100 requests in a 5-minute window.	Back off and retry after the window rolls over. See Rate limits for the exact limit and Retry guidance below.

5xx — Server errors

code	Meaning	What to do
FETCH_FAILED	The External API could not fetch data from the underlying E1 platform.	Retry with exponential backoff. If persistent, contact support.
INTERNAL_SERVER_ERROR	Something unexpected broke on our side.	Retry with exponential backoff. If persistent, contact support.

Retry guidance

• Retry 5xx responses with exponential backoff (e.g. 1s, 2s, 4s, 8s, up to ~60s). Do not retry aggressively.
• Retry 429 responses only after backing off. The API does not emit a Retry-After header — back off exponentially or wait until the 5-minute window has rolled over. See Rate limits — If you hit a throttle.
• Do not retry other 4xx responses (400, 403) — the request or the underlying licence needs to change before it will succeed.
• On 401 after a previously-succeeding call pattern, discard any cached token and fetch a new one before retrying once. If the retry fails, stop and investigate.

200 OK with empty data

A 200 with { "data": [] } is not an error. It means the call succeeded but nothing matched. Common causes:

• The assigned user has no Speci-finder keywords configured.
• No currently-open tenders match the assigned user’s keywords.
• All previously-matching tenders have already closed.

There is nothing to retry here — the response is authoritative.