Responses & Errors
The Surfe API utilizes standard HTTP status codes on its responses to reflect the result of API requests, whether they are successful or encounter errors.
Response bodies are sent as JSON objects. Responses with a 204 status have no body.
Successful responses
A successful request is accompanied by a 20X status code that confirms the operation was completed as expected.
| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and a result is returned |
| 201 | Created | The request succeeded and a new resource was created. The response includes the information to fetch the results |
| 202 | Accepted | The request was received successfully and an asynchronous process has started to handle the request. The response includes the information to fetch the results from this process |
| 204 | No response | The request succeeded but there is no content to return |
Error responses
In case of errors, the API responds with 4XX or 5XX status codes:
| Code | Status | Description |
|---|---|---|
| 400 | Bad Request | The request is invalid or malformed |
| 401 | Unauthorized | The API Key is missing or invalid |
| 402 | Payment Required | There are not enough credits available to handle the request |
| 403 | Forbidden | The request would exceed the quota, or the feature is not available in your plan |
| 404 | Not Found | The requested record cannot be found |
| 429 | Too Many Requests | The rate limit has been exceeded |
| 500 | Internal Server Error | There was an unrecoverable error on the server |
Error responses have a JSON body with a message field that explains what went wrong. Most also include a code field with the HTTP status code, and some include additional fields, which are documented on each endpoint: