Errors

Occasionally an error will be returned from the API, either because no data fit the request, invalid authentication, or (rarely) a problem internal to the API itself. Most errors are handled by the API, and you will receive a summary JSON output in lieu of data. Additionally, access restrictions within the Synoptic dataset are enforced by the API with errors for each request of data a token can’t access.

Errors will provide at least the following two elements:

Response Messages

The response messages typically help a user understand and correct the API error. These self-describing and brief explanations will describe the general reason for the error.

Response Code

The response codes correlate to a broader error type. Errors are grouped together based on the similar problematic requests types. Response codes are categories are listed as follows:

Response Code	Message
`-1`	Incorrect API parameter input
`1`	No errors
`2`	Zero results
`403`	Authorization error
`404`	URL not found
`500`	Internal errors

-1 - Incorrect API parameter input

These errors occur when an invalid input is passed through an API parameter.

JSON

{
  SUMMARY: {
    NUMBER_OF_OBJECTS: 0,
    RESPONSE_CODE: -1,
    VERSION: "v2.21.3",
    RESPONSE_MESSAGE: "START cannot be after END.",
    RESPONSE_TIME: 0
  }
}

Possible response code -1 messages:

Message	Description
`"START cannot be after END."`	`START` time requested is after `END` time requested, make sure your `START` time is before your `END` time.
`"Both START and END are required for a valid query."`	`START` and `END` times are required for Time Series. Advanced Precipitation, and Latency requests.
`"No latency data found for this request."`	This will only be returned as a response code -1 message for the Latency service. No latency data for the specified query.
`"No networks data found for this request."`	This will only be returned as a response code -1 message for the Networks service. No network data for the specified query.
`"No data found for this request."`	This will only be returned as a response code -1 message for the Networks Types and QC Types services. No data for the specified query.
`'WITHIN parameter required to use ATTIME.'`	In the Nearest Service, `WITHIN` (minutes) must be used with the `ATTIME` parameter.
`"LIMIT cannot be used without the RADIUS parameter."`	The `LIMIT` parameter only controls the number of return stations with the `RADIUS` parameter.
`"GROUPBY cannot be used with a QC query."`	The `GROUPBY` parameter cannot be used alongside ANY `QC` parameter.
`'UTF-8 Error'`	Make sure your query has properly encoded UTF-8 characters.
`'Unknown JSON encoding error.'`	The API was unable to properly output the requested data, please reach out to support@synopticdata.com with your query URL.

2 - No Results

Errors with a response code of 2 indicate no data was returned for a query due to various reasons.

JSON

{
SUMMARY: {
  RESPONSE_CODE: 2,
  RESPONSE_MESSAGE: "Invalid token. Be sure to use a token generated from your API Key, and not the key itself.",
  VERSION: null,
  HTTP_STATUS_CODE: 401
  }
}

These errors can also be returned outside of JSON format, such as:

NONE

{"SUMMARY": {"RESPONSE_CODE": 2, "RESPONSE_MESSAGE": "Too many requests sent. Please wait for other requests to finish and resend.", "VERSION": null, "HTTP_STATUS_CODE": 429}}

Possible response code 2 messages:

HTTP Status Code	Message	Description
	`"No stations found for this request, or your account does not have access to the requested station(s). Please contact support@synopticdata.com."`	No stations fitting your selection criteria. In the event that no data was found for the queried stations, this error will occur. This includes cases when two selection criteria cancel each other out. If you anticipate sometimes the request may return stations with no data, you can add `&showemptystations=1` to have `STATION` objects with empty `OBSERVATIONS` returned. More details on API Performance and Limits .
	`"Authorization error - mesonet API access not enabled for this contract"`	The token and its associated account does not have access enabled for the Weather Data API.
`401`	`"Invalid token. Be sure to use a token generated from your API Key, and not the key itself."`	The token passed is not recognized, the API key can’t be passed here instead of the token. Commonly occurs with mistyped tokens.
`403`	`"Unauthorized. Review your account access settings in the customer console.`"	Under “Customer & contract” in the Customer console, “Access” will indicate the data services (including the API) that an account has access to.
`400`	`"Request terminated"`	If you receive this error reach out to support@synopticdata.com with your query URL and indicate the account associated with the token.
`429`	`"Too many requests in the queue. Please wait for other requests to finish."`	You have reached your concurrency and request waitlist limit, you will have to wait to send more queries. Refer to API Performance and Limits for more details.
`503`	`"Unknown error in API."`	If you receive this error reach out to support@synopticdata.com with your query URL and indicate the account associated with the token.
`408`	`"Request could not complete. Timeout."`	The API request timed out after the limit of 360 seconds. Try the request again, if the error persists, please reach out to support@synopticdata.com.

403 - Authorization error

403 errors are directly tied to the levels of access an account and its access credentials have. If you receive one of these errors, refer to the features outlined with your usage tier on our pricing page or your signed commercial agreement.

JSON

{
  SUMMARY: {
    NUMBER_OF_OBJECTS: 0,
    RESPONSE_CODE: 403,
    VERSION: "v2.21.1",
    RESPONSE_MESSAGE: "Account associated with this token does not have access to the precipitation service. Please see our Enterprise Service options at https://synopticdata.com/enterprise, or contact us at account@synopticdata.com",
    RESPONSE_TIME: 0
  }
}

Possible response code 403 messages:

Message	Description
`"Authorization error - mesonet API access not enabled for this contract"`	The token and its associated account does not have access enabled for the Weather API.
`"Authorization error - no precip_access contract info"`	The token and its associated account does not have access to the Advanced Precipitation service. Please review the features associated with your contract on our pricing page.
`"Authorization error - missing precip_access contract info"`	The token and its associated account does not have access to the Advanced Precipitation service. Please review the features associated with your contract on our pricing page.
`"Authorization error - no qc_checks_access contract info"`	The token and its associated account does not have access to Advanced QC. Please review the features associated with your contract on our pricing page.
`"Account associated with this token does not have access to derived precipitation through the /timeseries endpoint. Please see our Enterprise Service options at https://synopticdata.com/enterprise, or contact us at account@synopticdata.com"`	The token and its associated account does not have access to Basic Precipitation through Time Series. Please review the features associated with your contract on our pricing page.
`"Account associated with this token does not have access to history earlier than x year(s). Please see our Enterprise Service options at https://synopticdata.com/enterprise, or contact us at account@synopticdata.com"`	The token and its associated account does not have access to historical data x year(s) before the current time. Please review the features associated with your contract on our pricing page.
`'The requested {} is not authorized for this account and token. Please modify your request.'`	The token and its associated account does not have access to one (or more) of the following requested parameters: STID Country State Please review the features associated with your contract on our pricing page.
`"Authorization error - no contract available"`	If you receive this error reach out to support@synopticdata.com with your query URL and indicate the account associated with the token.
`"Authorization error - no mesonet contract info"`	If you receive this error reach out to support@synopticdata.com with your query URL and indicate the account associated with the token.
`'Invalid history_access setting in customer contract. Should be int or null.'`	If you receive this error reach out to support@synopticdata.com with your query URL and indicate the account associated with the token.

404 - URL not found

These errors will occur if an incorrect URL is requested.

JSON

{
  SUMMARY: {
    RESPONSE_CODE: 404,
    VERSION: "v2.21.3",
    RESPONSE_MESSAGE: "Requested URL not found. See https://developers.synopticdata.com/mesonet/ for valid webservices.",
    RESPONSE_TIME: "0 ms"
  }
}

Possible response code 404 messages:

Message	Description
`"Requested URL not found. See https://developers.synopticdata.com/mesonet/ for valid webservices."`	The entered subdomain is correct `https://api.synopticdata.com/`, however, the URL refers to an incorrect service. The linked Developers site will have correct API endpoints.

500 - Internal Error

Errors internal to the API. If you continually receive one of these errors, please reach out to support@synopticdata.com with your query URL and indicate the account associated with the token.

JSON

{
  SUMMARY: {
    RESPONSE_CODE: 500,
    VERSION: "v2.21.1",
    RESPONSE_MESSAGE: "Internal error occurred.",
    RESPONSE_TIME: "0 ms"
  }
}

Possible response code 500 messages:

Message	Description
`"Internal error ocurred."`	If you receive this error reach out to support@synopticdata.com with your query URL and indicate the account associated with the token.