Errors

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:

Quote them when contacting support.