When something goes wrong, our API will send back a status code and a clear error message. Understanding these codes is the first step to debugging quickly!
These codes mean your request worked exactly as intended.
| Code | Name | What it Means |
|---|---|---|
| 200 | OK | The request was successful. This is typically for GET (fetching) and PUT/PATCH (updating) operations. |
| 201 | Created | A new resource was successfully created. You'll see this after a successful POST request. |
These codes mean you (the client) sent something the API didn't like. Check your request, parameters, and authentication.
| Code | Name | What Went Wrong | How to Fix It |
|---|---|---|---|
| 400 | Bad Request | The request data is invalid. You might be missing a required field, or a field value is in the wrong format (e.g., passing text where a number is expected). | Check the error body for a list of invalid fields. Review your request payload against the schema. |
| 401 | Unauthorized | Your request is missing valid authentication. You either didn't provide an API key, or the key you provided is invalid/expired. | Ensure you are passing a valid Authorization header with your API key or token. |
| 403 | Forbidden | You are authenticated, but lack permission. Your user or API key does not have the necessary roles/scopes to perform this specific action. | Contact your account administrator to update your permissions for this endpoint. |
| 404 | Not Found | The resource you requested does not exist. You might be trying to fetch a Payee ID that was deleted, or the URL path is misspelled. | Double-check the ID or path you are using. |
These codes mean the API failed for reasons outside of your control.
| Code | Name | What it Means (Plain English) | Action to Take |
|---|---|---|---|
| 500 | Internal Server Error | Something unexpected went wrong on our servers. This is usually a temporary issue. | Wait a moment and try the request again. If the error persists, please contact Theropay Support and provide the time, endpoint, and Request ID (if available). |
When a request fails, we always return a JSON object with helpful details:
{
"status": 400,
"error": "Bad Request",
"message": "Validation failed for payee.",
"details": [
{
"field": "payeeType",
"issue": "Must be either 'individual' or 'business'."
},
{
"field": "amount",
"issue": "Amount is required for this transaction."
}
],
"timestamp": "2025-10-09T09:30:00Z",
"request_id": "req_xyz123abc456"
}