Errors#

CasaPay uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with CasaPay's servers.

HTTP Status Codes#

Code	Description
`200 - OK`	Everything worked as expected
`201 - Created`	A new resource was successfully created
`400 - Bad Request`	The request was unacceptable, often due to missing a required parameter
`401 - Unauthorized`	No valid API key provided
`403 - Forbidden`	The API key doesn't have permissions to perform the request
`404 - Not Found`	The requested resource doesn't exist
`409 - Conflict`	The request conflicts with another request (idempotent replay)
`422 - Unprocessable Entity`	The request was well-formed but contained semantic errors
`429 - Too Many Requests`	Too many requests hit the API too quickly
`500 - Server Error`	Something went wrong on CasaPay's end

Error Response Format#

All errors return a JSON body with the following structure:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The 'amount' parameter is required.",
    "param": "amount",
    "doc_url": "https://docs.casapay.com/docs/getting-started/errors#parameter_missing"
  }
}

Error Types#

Type	Description
`api_error`	An error occurred internally (these are rare)
`authentication_error`	Failure to properly authenticate
`invalid_request_error`	Your request has invalid parameters
`rate_limit_error`	Too many requests
`validation_error`	Errors triggered by field validation
`idempotency_error`	The idempotency key was used for a different request

Error Codes#

Code	Description
`parameter_missing`	A required parameter was not provided
`parameter_invalid`	A parameter value is invalid
`resource_not_found`	The specified resource does not exist
`resource_already_exists`	A resource with this identifier already exists
`state_invalid`	The resource is not in a valid state for this operation
`amount_too_small`	The amount is below the minimum allowed
`amount_too_large`	The amount exceeds the maximum allowed
`currency_unsupported`	The currency is not supported
`rate_limit_exceeded`	API rate limit exceeded

Handling Errors#

We recommend writing code that gracefully handles all possible API exceptions:

try {
  const paymentIntent = await casapay.paymentIntents.create({
    amount: 120000,
    currency: 'eur',
  });
} catch (error) {
  switch (error.type) {
    case 'invalid_request_error':
      // Handle invalid parameters
      console.log(`Invalid parameter: ${error.param}`);
      break;
    case 'authentication_error':
      // Handle authentication failure
      break;
    case 'rate_limit_error':
      // Wait and retry
      break;
    default:
      // Handle unexpected errors
      break;
  }
}