Error codes

هذا المحتوى غير متوفر بلغتك بعد.

Every refusal comes in the same envelope, with a code from this list:

{"error": {"code": "SCOPE_MISSING",
           "message": "This client does not hold the invoices:read scope. Add it in Settings → Integrations.",
           "details": [{"scope": "invoices:read", "code": "SCOPE_MISSING"}],
           "request_id": "req_01J9X4Q7T2M8P3NRT6V5WZ",
           "retryable": false}}

message is written for you, the developer, and may name the field, the scope or the call to make first. Don’t parse it; branch on code.
retryable says whether the same call can succeed later. “What it means” below is the plain text the Slflo console shows for the same code.
Quote request_id (also in the X-Request-Id header) when you contact us.
A gateway in front of Slflo may answer 502, 503 or 504 without this envelope. Treat those like INTERNAL: back off and retry, honouring Retry-After when it is sent.

Code	HTTP	Retry?	What it means	What to do
`INVALID_REQUEST`	400 or 422	No	The request is not in the expected form. Check its parameters and body against the API documentation.	Fix the call (400) or the data (422, a rule on a pushed record): the message names the field.
`IDEMPOTENCY_KEY_REQUIRED`	400	No	The call had no Idempotency-Key, so it was not applied. Send one with every POST.	Send an Idempotency-Key header on every POST, PUT and DELETE.
`TOKEN_INVALID`	401	No	This integration token is not recognised. Check the token set in the ERP.	Stop the job and alert. Check the token in your settings.
`TOKEN_EXPIRED`	401	No	This integration token has expired. Create a new one in Settings → Integrations and update the ERP.	Stop the job and alert. Rotate the token in Settings → Integrations.
`TOKEN_REVOKED`	401	No	This integration token was revoked. Ask your administrator for a new one.	Stop the job and alert. Put the new token in your settings.
`COMPANY_SUSPENDED`	401	No	This company's account is suspended, so its integration tokens are not accepted. Contact Slflo support.	Stop the job and contact us.
`SCOPE_MISSING`	403	No	This integration is not allowed to do that. Add the missing permission to it in Settings → Integrations.	Ask the administrator to add the scope named in details to the client.
`IP_NOT_ALLOWED`	403	No	Calls from this address are not on the integration's allowlist. Add the address in Settings → Integrations.	Call from an address on the client's allow-list, or ask for yours to be added.
`NOT_FOUND`	404	No	It isn't there any more. Refresh and try again.	Check the id, path or reference list name.
`ALREADY_ACKNOWLEDGED`	409	No	The ERP already answered this order differently. It can answer again only after the order is sent to the ERP again.	The record was already answered differently. Treat it as done unless it is sent again.
`ORDER_NOT_AWAITING_ACK`	409	No	This order is not waiting for the ERP, so there is nothing for the ERP to answer.	The order is not waiting for your ERP. Pull filter[ack]=pending for the ones that are.
`ERP_MODE_NOT_API`	409	No	This company's orders are not set to be collected by its ERP, so the ERP cannot answer for them.	Order acks need the company in ERP mode API. Ask us to switch it.
`EXTERNAL_REF_CONFLICT`	409	No	That ERP reference already belongs to another record here. Each record answers to one ERP reference.	Your key already belongs to another record. Use one key per record; adopt with salflo_id.
`BRANCH_ON_ROUTE`	409	No	This branch is still on a route. Remove it from the route first.	Take the branch off its route in the console, then delete it.
`REQUEST_IN_PROGRESS`	409	Yes	The same call is still being processed. Try again in a few seconds.	The first call with this key is still running. Retry shortly with the same key.
`UNKNOWN_REFERENCE`	422	No	That refers to something the ERP has not sent yet. Send it first, then try again.	Push what details names first (the call is in the message); nothing was written.
`IDEMPOTENCY_KEY_REUSED`	422	No	That Idempotency-Key was already used for a different request. Use a new key for a new request.	A key goes with one request body. Use a new key for a different request.
`RATE_LIMITED`	429	Yes	Too many attempts. Wait a minute and try again.	Wait the Retry-After seconds, then send the same call again.
`INTERNAL`	500	Yes	Something went wrong on our side. Try again in a moment; if it keeps happening, quote the request number to support.	Retry with back-off; quote the request_id if it persists.

INVALID_REQUEST is 400 when the call itself is malformed (an unknown filter, a bad per_page) and 422 when a pushed record breaks a rule (a negative price, a key with a /). How to retry each status is in Retries, 429 and token rotation.