# Status codes

HTTP status codes returned by the Statsnet API.

The API returns an appropriate HTTP status code indicating whether the request was successful (e.g., `200 OK`) or failed (e.g., `403 Forbidden`). If a request fails, check the API response for more information.

## Success Codes

| Code | Status | Description |
| --- | --- | --- |
| `200` | OK | The request was successful. |
| `201` | Created | The resource was successfully created. |
| `204` | No Content | The request was successful but there is no content to return. |

## Client Error Codes

| Code | Status | Description |
| --- | --- | --- |
| `400` | Bad Request | The request was malformed or contains invalid parameters. |
| `401` | Unauthorized | The session or credentials expired, or the API key is invalid/revoked. |
| `402` | Payment Required | The account behind the API key has no active subscription (canceled or expired). |
| `403` | Forbidden | No access: anonymous caller on a protected endpoint, or the plan tier is too low. |
| `404` | Not Found | The requested resource does not exist. |
| `409` | Conflict | The request conflicts with the current state of the resource. |
| `422` | Unprocessable Entity | The request body contains semantic errors. |
| `429` | Too Many Requests | The monthly API-call allowance is exhausted or the per-minute burst limit was hit. Check the `X-API-Calls-Used` and `X-API-Calls-Limit` response headers. On report plans this code also means the period’s report quota is consumed. |

## Server Error Codes

| Code | Status | Description |
| --- | --- | --- |
| `500` | Internal Server Error | An unexpected error occurred on the server. |
| `502` | Bad Gateway | The server received an invalid response from an upstream server. |
| `503` | Service Unavailable | The server is temporarily unavailable. Retry the request later. |

## Error Response Format

When a request fails, the API returns a JSON object with error details:

**Error response example**

```json
{
  "status": 403,
  "message": "access denied"
}
```