# HTTP status codes

All API responses include an HTTP status code in the `status` parameter. A 200 status indicates success, while other codes identify specific error conditions. See the table below for details.

| Code | Response name         | Description                                                                                    |
| ---- | --------------------- | ---------------------------------------------------------------------------------------------- |
| 200  | OK                    | The request was successful.                                                                    |
| 400  | Bad Request           | The request had bad syntax or the parameters supplied were invalid.                            |
| 401  | Unauthorized          | A valid API key was not supplied in the query.                                                 |
| 403  | Forbidden             | The API key provided does not have access to the requested resource.                           |
| 404  | Not Found             | The server has not found a route matching the given URI.                                       |
| 429  | Too Many Requests     | The request rate limit has been exceeded.                                                      |
| 500  | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
| 501  | Not Implemented       | The server does not support the functionality required to fulfill the request.                 |
| 502  | Bad Gateway           | The server received an invalid response from the upstream server.                              |
| 503  | Service Unavailable   | The server is currently unable to handle the request due to temporary overload or maintenance. |
| 504  | Gateway Timeout       | The server did not receive a timely response from the upstream server.                         |

## Success response format

A successful response returns data in the format specified by the particular API endpoint. Refer to the individual API documentation pages for details.

## Error response format

Error responses follow the [RFC 7807 Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc7807) standard. Each error response contains both modern standardized fields and legacy fields for backward compatibility.

## Response fields

| Field             | Type   | Description                                                                                                 |
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `type`            | string | URI reference that identifies the problem type (e.g., `https://httpproblems.com/http-status/401`)           |
| `title`           | string | Human-readable summary of the error type                                                                    |
| `status`          | number | HTTP status code for this occurrence of the problem                                                         |
| `instance`        | string | URI reference that identifies the specific problem occurrence (request path without base URL)               |
| `trace.timestamp` | string | ISO 8601 timestamp when the error occurred (GMT)                                                            |
| `trace.requestId` | string | Unique identifier for this request (useful when contacting support)                                         |
| `trace.buildId`   | string | Build/deployment API gateway identifier                                                                     |
| `Code`            | string | **(Will be deprecated)** HTTP status text - use `title` and `status` instead                                |
| `Message`         | string | **(Will be deprecated)** Error message - use `title` instead                                                |
| `Reference`       | string | **(Will be deprecated)** Full URL of the request - use `instance` instead (note: includes query parameters) |

### Legacy keys—to be deprecated

:::warning{title="Deprecated Fields"}

The following fields exist only for backward compatibility with legacy clients and **will be removed in a future version**:

- **`Code`** - Replaced by `title` (text) and `status` (numeric)
- **`Message`** - Replaced by `title`
- **`Reference`** - Replaced by `instance` (without base URL)

Use the modern keys for new integrations.

:::

## Example error response

This is a complete example of an error response for an unauthorized request:

```json
{
  "type": "https://httpproblems.com/http-status/401",
  "title": "Unauthorized",
  "status": 401,
  "instance": "/currentconditions/v1/349727",
  "trace": {
    "timestamp": "2025-10-06T14:21:53.918Z",
    "requestId": "3b0b8539-a290-4fdd-b83e-9b7f989dea44",
    "buildId": "6e3881ec-0837-46a0-b8f4-344ea529b089"
  },
  "Code": "Unauthorized",
  "Message": "API authorization failed",
  "Reference": "https://dataservice.accuweather.com/currentconditions/v1/349727?apikey=REDACTED&details=true"
}
```

When handling errors, use the modern `status` field for the numeric HTTP code, `title` for a user-friendly error name, and `trace.requestId` when contacting support. The legacy fields (`Code`, `Message`, `Reference`) are provided for backward compatibility but should not be used in new integrations.