# Response Codes

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!

## Success Codes: All is Well

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. |


br
## Client Error Codes (4xx): Fix it on Your Side

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. |


br
## Server Error Codes (5xx): That's on Us

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). |


## Error Response Body

When a request fails, we always return a JSON object with helpful details:


```json
{
  "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" 
}
```