Error Handling

When something goes wrong, we'll give you a clear error response that tells you what happened and why. Every error follows the same shape, so you can handle them consistently.

What errors look like

{
  "status": 400,
  "errorCode": "yp_2002",
  "message": "Request validation failed",
  "errorType": "validation"
}

Field	Type	What it is
status	integer	The HTTP status code.
errorCode	string	A Yeti error code like yp_2002. Use this in your code to handle specific errors.
message	string	A human-readable explanation. For validation errors, this will tell you which fields have problems.
errorType	string	The category: security, validation, internal, or configuration.

All the error codes

Security (yp_1xxx)

Something's up with authentication or authorisation.

Code	Status	Message	What it means
yp_1001	401	Unauthorized	Your API key is missing, invalid, or expired.
yp_1002	403	Forbidden	The key's fine, but it's not allowed to access this endpoint.

Validation (yp_2xxx, yp_3xxx)

There's a problem with the request or with something it references.

Code	Status	Message	What it means
yp_2001	400	Bad request	The request doesn't make sense to us.
yp_2002	400	Request validation failed	One or more fields aren't right. Check the message for specifics.
yp_3001	404	Resource not found	Whatever you're looking for doesn't exist.
yp_3002	404	Merchant not found	We can't find a merchant linked to your API key.
yp_3003	404	Site not found	The siteId in your URL doesn't match any site we know about.
yp_3004	409	Request not allowed for this site type	The site exists, but it's not set up as an ecommerce site.
yp_3004	404	Site cannot be found	We couldn't find the site during setup.
yp_3005	404	Merchant not found	We couldn't find the merchant during setup.

Payment processing (yp_4xxx)

Something went wrong while talking to the payment processor.

Code	Status	Message	What it means
yp_4001	500	Payment processing failed	A general payment failure.
yp_4002	500	Failed to retrieve payment methods	We couldn't get the payment methods.
yp_4003	500	Failed to capture payment	The capture didn't go through.
yp_4004	500	Failed to submit payment details	We couldn't submit the 3DS details.
yp_4005	500	Failed to refund or cancel payment	The reversal didn't work.
yp_4006	500	Failed to start payment	We couldn't start the payment.
yp_4007	500	Failed to update authorised amount	The amount update didn't go through.
yp_4008	500	Failed to create session	We couldn't create the checkout session.

Configuration (yp_5xxx)

Something's not set up right on your account.

Code	Status	Message	What it means
yp_5001	404	Configuration not found	A piece of configuration we need is missing.
yp_5003	422	Merchant is not properly configured	Your merchant account isn't set up for ECOM payments yet. Get in touch with support.

Gateway (yp_9xxx)

These come from the API gateway before your request even reaches us.

Code	Status	Message	What it means
yp_9001	500	Internal server error	Something unexpected happened at the gateway.
yp_9002	400	Bad request	The gateway couldn't make sense of the request.
yp_9003	401	Unauthorized	Authentication failed at the gateway.
yp_9004	401	Unauthorized	Access denied at the gateway.
yp_9005	404	Not found	That endpoint doesn't exist. Double-check the URL.
yp_9006	429	Too many requests	You're sending too many requests. Slow down and try again in a bit.

Common problems and how to fix them

Getting a 401?

• Check the Authorization header is there and looks like Bearer YOUR_API_KEY.
• Make sure the key hasn't been turned off or expired.
• If you're on the test environment, check you're using a test key (and vice versa for production).

Getting a 403?

• Your key is valid, but it isn't allowed to access this endpoint.
• If the error code is yp_1002 and you're sure your setup is correct, check that your merchant's ECOM checkout key is configured.

Getting a 400 with yp_2002?

• The message field will tell you exactly which fields have problems. Common culprits:
  • Missing amount (most endpoints need it, with both value and currency).
  • returnUrl isn't a valid URL.
  • reference is longer than 80 characters.

Getting a 404 for a site or merchant?

• Double-check the siteId in your URL matches an ecommerce site on your merchant account.
• The site needs to be set up as type Ecommerce -- other types won't work here.

Getting a 422?

• Your merchant account needs to be configured for ECOM payments. Get in touch with your account manager or support to sort this out.

Getting a 429?

• You're being rate limited. Wait a moment and try again. Have a look at Best Practices for how to handle this properly.

Getting a 500?

• These usually mean something went wrong with the payment processor. They're often temporary.
• Try the request again with the same idempotency key.
• If it keeps happening, get in touch with support and include the error code and your request details.