Guides

Errors

What Payjar returns when a key, field, or payment is not valid, and what to do next.

Payjar business errors use the normal envelope and a 4xx status.

HTTP	Message	What to do
401	`Invalid API key.`	Check the key, the `Bearer` prefix, and that the key has not been replaced.
403	`This profile is not active.`	The store is switched off.
403	`This profile is not live yet.`	You used a live key before the store went live. Use a test key, or go live first.
400	`A valid customer email is required.`	Send `email` or `customer_email`.
400	`reference is required.`	The simulate call needs `reference`.
400	`Payment not found.`	That reference is not on this store, in this test or live mode. HTTP `404` on verify.
400	`This payment has expired.`	Start a new payment, or call initialize again with the same unpaid reference to get a new 30 minutes.
400	`Payments can only be simulated in test mode.`	Use `sk_test_...`.
400	`No settlement account is available for this profile yet.`	The store cannot receive a transfer yet.
400	`Could not generate a payment account. Please try again.`	Payjar could not open an account number. Try the request again.
400	`This profile has been suspended.`	The store cannot take payments.
404	`Payment not found.`	Verify was called with an unknown reference.
422	Validation message	A field is missing or invalid. See below.
429	Too many requests	Stay under 60 requests a minute per IP.

Validation error#

HTTP 422 uses a different shape. There is no success field.

Request

{
  "amount": 0
}

422Response

{
  "message": "The amount field must be at least 1.",
  "errors": {
    "email": [
      "The email field is required when customer email is not present."
    ],
    "amount": [
      "The amount field must be at least 1."
    ]
  }
}

The popup shows errors text in the modal and calls onError.

Situation	What happens
No public key and no `access_code`	Modal shows `A valid Payjar public key is required.`
Bad key	Modal shows `Invalid API key.`
Payjar cannot create the session	Modal shows the `message` from Payjar.
Customer closes the window	`onClose` runs. The payment can still succeed later.
Timer runs out	`onClose` runs. Status becomes `expired`.

Errors

Validation error#

Popup errors#