HTTP Error Codes in the Visual Crossing Weather API

The Visual Crossing Weather API uses standard HTTP response status codes to indicate whether a request succeeded or failed.

When a request fails, always check both:

1. The HTTP status code.
2. The response body returned by the API.

The status code identifies the general type of problem, while the response body will normally contain additional information describing the specific cause.

The Visual Crossing Weather API provides historical weather, current conditions, forecasts, and other weather data through HTTP-based APIs.

To get started, sign up for a free Visual Crossing account and obtain your API key.

For the complete Timeline API reference, see the Timeline Weather API documentation.

Weather API HTTP response codes

The main HTTP status codes returned by the Weather API are:

Status	Name	Meaning
200	OK	The request was processed successfully
400	BAD_REQUEST	The request is malformed or contains invalid parameters
401	UNAUTHORIZED	There is a problem with the API key, account, subscription, or feature access
404	NOT_FOUND	The URL does not match a valid Weather API endpoint
429	TOO_MANY_REQUESTS	The account has exceeded an assigned usage, rate, or concurrency limit
500	INTERNAL_SERVER_ERROR	An unexpected error occurred while processing the request

Applications should not rely only on the numeric status code. The response body often provides the information needed to identify the exact problem.

200 OK

A 200 OK response means that the Weather API successfully processed the request.

For example:

HTTP/1.1 200 OK

Your application can then process the returned JSON, CSV, or other requested response format.

A successful HTTP status does not necessarily mean that every possible weather field contains a value. Some weather elements may be unavailable for a particular location, time, source, or request and can therefore contain null or missing values.

Your application should handle missing weather values separately from HTTP request failures.

400 BAD_REQUEST

A 400 BAD_REQUEST response means that the request reached the Weather API but could not be processed because the request itself is invalid.

Common causes include:

• Invalid dates
• Invalid date ranges
• Invalid parameter values
• Unsupported combinations of parameters
• Malformed locations
• Invalid include values
• Invalid elements
• Incorrectly constructed request URLs

For example, a malformed date might produce a request such as:

/timeline/London,UK/2026-99-99

The API may return:

400 BAD_REQUEST

along with a response body explaining which part of the request is invalid.

What to do

When you receive a 400 response:

1. Read the response body.
2. Check the location and dates.
3. Verify the names and values of query parameters.
4. Compare the request with the Timeline Weather API documentation.
5. Test a simplified version of the request.

For example, if a complex request fails, temporarily reduce:

include=current,days,hours,alerts,events

to:

include=days

and add options back until the problem is identified.

401 UNAUTHORIZED

A 401 UNAUTHORIZED response indicates an authentication, account, subscription, or permission problem.

Possible causes include:

• Missing API key
• Invalid API key
• An API key that has been replaced
• Inactive or disabled account
• Subscription issue
• Attempting to access a feature not included with the account
• Attempting to use an API that requires additional access

For example:

?key=YOUR_API_KEY

must contain a valid API key for the account.

Check your API key

Make sure that:

• The key parameter is present.
• The key has not been truncated.
• There are no extra spaces.
• The application is using the current key.
• The URL is constructed correctly.

If you recently generated a new API key, applications still using the old key must be updated.

See How to Find and Change Your Weather API Key.

Check feature access

A 401 can also occur when the API key itself is valid but the requested feature is not available on the account.

For example, some specialized Weather API features depend on the subscription or license.

In this case, the response body should help identify the unavailable feature.

404 NOT_FOUND

A 404 NOT_FOUND response means that the request URL does not match a valid Weather API endpoint structure.

This is different from requesting a location that cannot be resolved.

A 404 generally indicates that the URL path itself is wrong.

For example, a correct Timeline request follows a structure such as:

/VisualCrossingWebServices/rest/services/timeline/[location]/[date1]/[date2]

A misspelled endpoint path may instead return:

404 NOT_FOUND

What to check

Verify:

• The hostname
• /VisualCrossingWebServices/
• /rest/services/
• The API endpoint name
• The ordering of path components
• Whether you are using a current rather than retired endpoint

For current development, the Timeline Weather API should normally be used for historical weather, current conditions, and forecasts.

429 TOO_MANY_REQUESTS

A 429 TOO_MANY_REQUESTS response means that the account has exceeded one of its assigned request or usage limits.

Depending on the product and account, this can include limits related to:

• Request rate
• Concurrent requests
• Daily usage
• Monthly usage
• Other plan-specific limits

Visual Crossing plans include usage and request limits, and automated applications should be designed to operate within the limits of the account being used.

Concurrency limits

A concurrency limit controls how many requests can be actively processed at the same time.

For example, if an application starts many requests simultaneously, some requests may return:

429 TOO_MANY_REQUESTS

even if the account’s total usage allowance has not been exhausted.

Applications should control the number of simultaneous requests rather than repeatedly overwhelming the account’s concurrency limit.

Usage limits

A 429 can also indicate that another assigned account limit has been reached.

Always inspect the response body rather than assuming that every 429 means the same thing.

Retrying a 429 response

If the response is caused by temporary concurrency, a request can generally be retried after active requests complete.

However, retry logic should not be used to intentionally circumvent account limits.

Do not create aggressive retry loops such as:

request
429
retry immediately
429
retry immediately
429
...

Instead:

• Control the number of concurrent requests.
• Use a sensible delay before retrying transient failures.
• Limit the number of retries.
• Stop retrying if the account has exhausted a non-transient usage allowance.
• Review the account’s current usage and limits.

For more information about concurrency errors, see What is the cause of “Maximum concurrent jobs has been exceeded”, HTTP response 429.

500 INTERNAL_SERVER_ERROR

A 500 INTERNAL_SERVER_ERROR response means that an unexpected error occurred while the Visual Crossing service was processing the request.

For example:

500 INTERNAL_SERVER_ERROR

This differs from a 400 response because the request may be valid even though the server was unable to complete it.

What to do

First, preserve:

• The complete request URL, with the API key removed or obscured
• HTTP status code
• Response body
• Approximate request time
• Any request identifier or relevant response headers
• Whether the problem occurs consistently or intermittently

If the request normally succeeds, retrying it after a short interval may be appropriate for an isolated server-side failure.

If the error continues, contact Visual Crossing Support with an actionable technical support case.

See Helping Us Help You: How to Submit an Actionable Technical Support Case.

Always inspect the response body

One of the most important Weather API debugging practices is to capture the response body even when the HTTP request returns an error.

For example, do not write code that only reports:

Request failed with HTTP 400

when the API may also have returned a useful message describing the invalid parameter.

Log or inspect:

HTTP status
response headers
response body

before trying to diagnose the problem.

Python example

With Python’s requests package:

import requests

response = requests.get(
    weather_api_url,
    timeout=20
)

if not response.ok:
    print(
        "HTTP status:",
        response.status_code
    )

    print(
        "Response:",
        response.text
    )

    response.raise_for_status()

weather = response.json()

This preserves the API error message before raising an exception.

JavaScript example

Using fetch():

const response = await fetch(
    weatherApiUrl
);

if (!response.ok) {
    const message =
        await response.text();

    throw new Error(
        `Weather API request failed ` +
        `(${response.status}): ${message}`
    );
}

const weather =
    await response.json();

Java example

Using Java’s HttpClient:

HttpResponse<String> response =
    httpClient.send(
        request,
        HttpResponse.BodyHandlers.ofString()
    );

if (response.statusCode() < 200 ||
    response.statusCode() >= 300) {

    throw new RuntimeException(
        "Weather API request failed (" +
        response.statusCode() +
        "): " +
        response.body()
    );
}

cURL example

For command-line testing, cURL can display the API error body while also returning a failure exit code:

curl \
  --show-error \
  --fail-with-body \
  "WEATHER_API_URL"

For more cURL examples, see How to Use cURL to Download Weather Data.

Distinguish HTTP errors from missing weather data

An HTTP error means that the request itself could not be successfully processed.

Missing or null weather fields are different.

For example, a successful response might contain:

{
  "temp": 72.4,
  "snowdepth": null
}

This is still a successful API request and should not be treated as an HTTP error.

Applications should separately handle:

1. HTTP/request errors.
2. JSON or response-format errors.
3. Missing individual weather values.

Common debugging workflow

When a Weather API request fails:

1. Capture the HTTP status.
2. Read the response body.
3. Confirm that the API key is present and valid.
4. Verify the endpoint and URL structure.
5. Check the location and dates.
6. Check the request parameters.
7. Review account usage and feature access.
8. Reduce the request to a simple known-good query if necessary.

For a more complete troubleshooting process, see How to Debug Problems When Running Weather API Queries in Code.

Do not expose API keys in support cases

When copying an API request into:

• Support tickets
• Emails
• Forums
• Screenshots
• Public issue trackers

remove or obscure the API key.

For example, change:

key=ABCDE12345REALKEY

to:

key=YOUR_API_KEY

Visual Crossing Support can investigate account-specific issues without requiring you to publish a credential.

If you believe your API key has been exposed, replace it from your account.

Other Visual Crossing APIs

The HTTP status codes described here are the primary codes used throughout Visual Crossing Weather API services.

Individual APIs may have additional endpoint-specific details.

For example:

• Timeline Weather API
• Timeline LLX Weather API
• Historical Forecast API
• Weather Maps API
• Stored Dataset APIs

When working with a specialized API, also review that API’s specific documentation.

The main Timeline Weather API currently documents the same primary 200, 400, 401, 404, 429, and 500 response-code model.

Getting help

If you cannot identify the problem from the HTTP status and response body, collect enough information to reproduce the request.

Useful information includes:

• API endpoint
• Location
• Date or date range
• Request parameters
• HTTP status
• Response body
• Approximate request time
• Programming language or HTTP client

Do not include your API key in publicly visible troubleshooting information.

For technical assistance, use Visual Crossing Support.

Summary

The Visual Crossing Weather API uses standard HTTP response codes to communicate request status.

The primary codes are:

200 OK
400 BAD_REQUEST
401 UNAUTHORIZED
404 NOT_FOUND
429 TOO_MANY_REQUESTS
500 INTERNAL_SERVER_ERROR

Use the status code to identify the general category of the problem, but always inspect the response body for the specific error information.

In particular:

• 400 usually means the request or parameters are invalid.
• 401 indicates authentication, account, subscription, or feature-access problems.
• 404 usually means the endpoint URL is incorrect.
• 429 means an assigned request or usage limit has been exceeded.
• 500 indicates an unexpected server-side processing error.

For broader troubleshooting guidance, see How to Debug Problems When Running Weather API Queries in Code.