Errors

The API uses standard HTTP status codes and returns JSON error bodies.

HTTP Status Codes

Error Response Format

The API returns errors in the following format:

1
{
2
  "message": "Checkout Inválido",
3
  "errors": {
4
    "items": ["can't be blank"]
5
  }
6
}

The message field is always present. The errors object is optional and contains field-level validation details.

Common Errors

Authentication Failed

1
// 401
2
{
3
  "message": "Autenticación Errónea 👀",
4
  "errors": {
5
    "authentication": [
6
      "Las llaves de API son inválidas o no coinciden."
7
    ]
8
  }
9
}

Your API keys are invalid, missing, or don’t match the same account/environment.

Validation Error

1
// 400
2
{
3
  "message": "Producto Inválido",
4
  "errors": { "name": ["can't be blank"] }
5
}

The provided parameters don’t pass validation. Check the errors object for specific details.

Cannot Modify Paid Checkout

1
// 422
2
{ "message": "No se puede modificar un checkout pagado" }

You tried to modify a checkout that has already been paid.

Resource Not Found

1
// 404
2
{ "message": "Producto no encontrado" }

The requested resource doesn’t exist or doesn’t belong to your account.

Error Handling

Always check the HTTP status code before processing the response:

1
if (response.status >= 400) {
2
  const error = await response.json();
3
  console.error('API Error:', error.message);
4
  
5
  // Handle specific validation errors
6
  if (error.errors) {
7
    Object.keys(error.errors).forEach(field => {
8
      console.error(`${field}: ${error.errors[field].join(', ')}`);
9
    });
10
  }
11
}