Errors

In this guide, we will talk about what happens when something goes wrong while you work with the Swypex Partner API. Let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong.

The API returns structured error responses with both a human-readable message and a machine-readable error type.

Status codes

Here is a list of the different categories of status codes returned by the Swypex Partner API:

Name
200 OK
Description
The request was successful. The response body contains the requested data.
Name
400 Bad Request
Description
The request was malformed or contains invalid parameters.
Name
401 Unauthorized
Description
Authentication failed or the access token is invalid/expired.
Name
403 Forbidden
Description
The authenticated client doesn't have permission to access the resource (insufficient scopes).
Name
404 Not Found
Description
The requested resource doesn't exist.
Name
422 Unprocessable Entity
Description
The request was well-formed but contains semantic errors (e.g., validation failures).
Name
429 Too Many Requests
Description
Rate limit exceeded. Slow down your requests.
Name
500 Internal Server Error
Description
Something went wrong on the server. Contact support if this persists.
Name
503 Service Unavailable
Description
The API is temporarily unavailable. Try again later.

Error response structure

All error responses follow a consistent structure with two fields:

Name
message
Type
string
Description
A human-readable error message describing what went wrong. Use this to understand the error and take corrective action.
Name
type
Type
string
Description
A machine-readable error type that categorizes the error. See error types below.

Error response example

{
  "message": "Card not found",
  "type": "NotFound"
}

Error types

The API uses three error types to categorize errors:

Name
NotFound
Description
The requested resource doesn't exist. Check that you're using the correct ID.
Name
InvalidRequest
Description
The request is malformed or contains invalid parameters. Check the error message for details on what's invalid.
Name
InternalError
Description
An unexpected error occurred on the server. If this persists, contact Swypex support.

NotFound error

{
  "message": "Card not found",
  "type": "NotFound"
}

InvalidRequest error

{
  "message": "Invalid limit value: must be between 0 and 300000000",
  "type": "InvalidRequest"
}

InternalError

{
  "message": "An unexpected error occurred. Please try again.",
  "type": "InternalError"
}

Common errors and solutions

Here are some common errors you might encounter and how to resolve them:

Authentication errors

401 Unauthorized - Invalid or expired token

{
  "message": "Invalid or expired token",
  "type": "InvalidRequest"
}

Solution: Request a new access token using your client credentials.

403 Forbidden - Insufficient scopes

{
  "message": "Insufficient permissions to access this resource",
  "type": "InvalidRequest"
}

Solution: Ensure your access token includes the required scopes (cards:read for read operations, cards:write for write operations).

Resource errors

404 Not Found - Card doesn't exist

{
  "message": "Card not found",
  "type": "NotFound"
}

Solution: Verify the card ID is correct and the card exists in your organization.

Validation errors

422 Unprocessable Entity - Invalid limit value

{
  "message": "Daily limit exceeds maximum allowed value of 100000000 cents",
  "type": "InvalidRequest"
}

Solution: Check the API documentation for valid ranges. Remember that all limits are in cents, not pounds.

422 Unprocessable Entity - Missing required fields

{
  "message": "Missing required field: monthly",
  "type": "InvalidRequest"
}

Solution: When using PUT to set limits, you must provide all four limit fields (daily, monthly, atm, approval_based). Use PATCH to update only specific fields.

Rate limiting

429 Too Many Requests

{
  "message": "Rate limit exceeded. Please slow down your requests.",
  "type": "InvalidRequest"
}

Solution: Implement exponential backoff and respect the rate limits. Contact support if you need higher limits.

Suggested Best practices

Always check status codes: Don't assume requests succeed. Check the HTTP status code before parsing the response.
Log error details: Log both the message and type fields for debugging.
Handle errors gracefully: Display user-friendly error messages to end users while logging technical details.
Implement retry logic: For 500/503 errors, implement exponential backoff retry logic.
Validate before sending: Validate request parameters client-side to catch errors before making API calls.
Monitor error rates: Track your error rates to identify issues early.