Errors
Related
Keep reports a failed request with an HTTP status code and, in most cases, a JSON body. The token endpoint and the other endpoints use different body shapes, and a few responses are plain text.
Token endpoint errors
POST /oauth2/token errors return error and error_description, plus correlationId and category:
{
"error": "unauthorized_client",
"error_description": "Invalid client"
}
| HTTP status | error |
error_description |
Cause |
|---|---|---|---|
| 401 | unauthorized_client |
Invalid client |
Unknown client ID, or wrong client secret. |
| 401 | unauthorized_scope |
The scope you asked for is not granted to your client. | |
| 403 | access_denied |
Invalid client |
Your client is not linked to a Keep user. Contact your Account Manager. |
| 400 | invalid_request |
Invalid refresh token |
The refresh token is unknown or was already used. Request a new token with your client credentials. |
When client_id or client_secret is missing, the 401 body is the plain text Unauthorized, not JSON.
Errors from the other endpoints
Every other endpoint returns errors in this shape:
{
"statusCode": 400,
"message": ["Value of socialId field should be a valid Social ID"],
"error": "Bad Request"
}
| Field | Meaning |
|---|---|
statusCode |
The HTTP status code. |
message |
The error message. A list for validation errors, one entry per failed rule. |
error |
The error type, such as Bad Request or Unprocessable Entity. |
correlationId |
The ID of this failure. Quote it when contacting support. |
category |
The kind of error. Present on most errors. |
A validation error lists each failed rule, for example on Upload expense document:
{
"statusCode": 400,
"message": [
"socialId must be a number conforming to the specified constraints",
"socialId should not be empty",
"email must be an email",
"email should not be empty",
"sellerId must be a UUID",
"sellerId should not be empty"
],
"error": "Bad Request"
}
Server errors
An unexpected failure on Keep's side returns 500 with statusCode and correlationId and no message. Quote the X-Correlation-Id header (see Request IDs) when contacting support. Whether you can send the request again depends on the endpoint: see Retrying a request.
HTTP status codes
| Status | What it means in Keep |
|---|---|
| 400 | The request failed validation, or was refused with a message of its own (see the table below). On Create seller and on the Seller API's Create income document, a failure in another system Keep relies on is also returned as 400 with that system's message, so a 400 there is not always a mistake in your request. |
| 401 | The access token is missing or expired: {"message":"Unauthorized","statusCode":401}. Get a new token (Token requests). |
| 403 | Forbidden resource — the token does not have the required scope. Or the seller does not belong to your partner account (each endpoint's message is in the table below). Or, on the Seller API, the seller cannot issue documents now. |
| 404 | The statistics endpoints found no seller with this ID number: Seller not found. |
| 422 | The request is valid but cannot be processed, for example Could not resolve seller or Bad seller configuration. Please contact support!. |
| 429 | Too many requests (see Rate limits). |
| 500 | An unexpected failure on Keep's side (see Server errors). |
Messages by endpoint
The messages each endpoint documents, beyond validation errors:
| Endpoint | Status | Message or cause |
|---|---|---|
| Create seller | 400 | Social ID is invalid — a Keep seller already uses this ID number. The email is invalid. Please try again — a Keep account already uses this email. Other onboarding errors are returned as 400 with their own message. |
| Get seller | 200 | Takes the seller ID or MPL in the path. Returns payload: null when the seller does not exist or does not belong to your partner account; this is not an error. |
| Update seller | 400 | Validation failed (uuid v 4 is expected) — sellerId is not a UUID v4. Bad identifier — the seller does not exist. |
| Update seller | 403 | The seller does not belong to your partner account. |
| Set seller billing plan | 200 | A successful response can carry Please complete payment to activate plan when payment is still needed. |
| Set seller billing plan | 400 | Bad seller identifier — the seller is unknown. |
| Set seller billing plan | 403 | Forbidden — the seller does not belong to your partner account. |
| Set seller billing plan | 422 | Bad seller configuration. Please contact support! |
| Upload expense document | 422 | Could not resolve seller; File URL is not reachable. |
| List expenses | 403 | Forbidden — the seller does not belong to your partner account. |
| List expenses | 422 | Could not resolve seller — the identifiers match no seller. |
| Update expense | 400 | Bad identifier — the expense does not exist. |
| Update expense | 403 | Forbidden — you are not authorized to update this expense. |
| Update expense | 422 | Only expenses with pending status can be updated, Could not resolve seller, Provided supplier ID is invalid, Invalid classification. |
| Create manual income document | 400 | Bad document number — the number is not accepted; a number starting with 514 or 515 is refused. Bad seller identifier. There is already document with the same number. Could not get file!. Provided Osek Type does not match the one on record. Please update your Osek Type with your courier partner before uploading documents. |
| List income documents (Partner API) | 400 | At least one of sellerPaymeId or sellerId should exists, Bad seller identifier. |
| Get financial checkpoints, Get tax predictions | 404 | Seller not found — no seller has this ID number. |
| Create income document (Seller API) | 202 | Success: the document is accepted and issued asynchronously. |
| Create income document (Seller API) | 400 | Bad seller identifier; Seller is not active. |
| Create income document (Seller API) | 403 | The seller cannot issue documents now: invoicing is not set up, the trial has ended, or the seller is closed. |
| Create income document (Seller API) | 422 | Client socialId should be provided for document with total amount above 23,600 NIS — the client socialId is required for documents of 23,600 ILS and above. Your invoice Israel token is invalid (with renewTokenUrl, where the seller renews the Israel Tax Authority connection). Record already exists. |
| Get income document (Seller API) | 400 | id is not a UUID. |
When nothing matches, Get income document returns 200 with payload set to null, not an error.
Retrying a request
When a request times out, you do not know whether Keep carried it out. What happens if you send the same request again:
| Endpoint | Sending the same request again |
|---|---|
| Obtain access token (client credentials) | Safe. You get a new token. |
| Obtain access token (refresh) | Not safe to repeat: a refresh token works once. Request a new token with your client credentials. |
| Create seller | No second seller is created: the repeat is refused with 400 Social ID is invalid or The email is invalid. Please try again. Check with Get seller before retrying. |
| Update seller | Safe. |
| Set seller billing plan | Ends on the same plan. Avoid repeating it needlessly: each call re-applies the plan. |
| Upload expense document | Not safe. Each call stores a new expense. Check List expenses before retrying. |
| Update expense | Safe. |
| Create manual income document | A repeat with the same document number is refused with 400 There is already document with the same number. Send one request at a time for a given document number. |
| Create income document (Seller API) | Not safe. Each call issues a new document. Check List income documents before retrying. |
For 429 and 500, wait before retrying and lengthen the wait after each failed attempt (exponential backoff); for 429, wait at least the time in Retry-After.
Rate limits
Requests to /api/public/sellers, /api/public/expenses and /api/public/plans are counted per partner domain in one-minute windows, as one shared allowance across those endpoints. Requests that fail also count. Your allowance is set per partner: ask your Account Manager for yours.
When the allowance is used up, these endpoints return HTTP 429. The 429 body is plain text, not the JSON error shape. Read the RateLimit-* response headers to see your remaining allowance, and wait for the time in the Retry-After header before retrying.
The Seller API's Create income document can also return 429, with a Retry-After header, when too many write requests are sent in a short time.
Request IDs
Responses carry two IDs, error responses included:
X-Request-Id— if you send your ownX-Request-Id, Keep reuses it and echoes it back; otherwise Keep generates one.X-Correlation-Id— always generated by Keep.
Quote them when contacting support.