Skip to main content

Error Handling

Applies To: Core APIs

The error structures on this page apply to the Nowcast API, Tide API, and Weather Stations API. Classic APIs have their error handling detailed individually within their respective sections in the API Catalog.

MetService's public API Platform uses standard HTTP status codes to indicate the success or failure of a request. When a request fails, the API returns a structured error body in JSON format, consistent with RFC 9457. This provides detailed, machine-readable information about the problem.

Note: To ensure zero ambiguity during critical incidents, all system-level error messages are provided in English. This allows automated monitoring systems to trigger reliably regardless of locale.

The type field in the error response is a URI that links directly to the relevant error description on this page. It names the problem type, which is independent of the HTTP status code (the status is carried separately in the status member), so each type uses a semantic slug (#not-found), not a status-numbered one.

Common Error Types​

400 Invalid Parameters​

  • Status Code: 400 Bad Request
  • Description: The request could not be understood by the server due to malformed syntax or invalid parameters. This could be due to an incorrectly formatted date or a missing required field.
  • User Action: Check the request body and parameters to ensure they are correctly formatted and that all required fields are present. The invalid_params array in the response will provide specific details.

Example Response:

{  
  "type": "https://developer.metservice.com/docs/error-handling/#invalid-parameters",  
  "title": "Invalid Parameters",  
  "status": 400,  
  "detail": "One or more request parameters failed validation.",  
  "instance": "/point/SNZ123456?from=yesterday",  
  "invalid_params": [  
    {  
      "name": "from",  
      "reason": "must be a valid ISO 8601 date-time"  
    }  
  ]  
}

401 Unauthorized​

  • Status Code: 401 Unauthorized
  • Description: The request lacks valid authentication credentials. This means the Authorization header is either missing or contains an invalid key.
  • User Action: Ensure the Authorization header is included in your request and that the key is correct and valid.

Example Response:

{  
  "type": "https://developer.metservice.com/docs/error-handling/#unauthorized",  
  "title": "Unauthorized",  
  "status": 401,  
  "detail": "A valid API key was not provided in the 'Authorization: Bearer <your-api-key>' header."  
}

403 Forbidden​

  • Status Code: 403 Forbidden
  • Description: The request is refused. This occurs if your API key lacks permissions for the requested resource, or if your request is missing a required User-Agent HTTP header.
  • User Action:
    • Insufficient Permissions: Verify that your API key has permissions for the target resource. Use the contact form if additional access is needed.
    • Missing User-Agent Header: Ensure your HTTP client explicitly sets a non-empty User-Agent header (e.g., -H "User-Agent: MyApp/1.0"). Note that interactive tools like cURL and Postman inject a User-Agent automatically, but custom programmatic clients or Cloudflare Workers may omit it.

Example Response:

{  
  "type": "https://developer.metservice.com/docs/error-handling/#forbidden",  
  "title": "Forbidden",  
  "status": 403,  
  "detail": "Your API key is not authorised to access location 'SNZ123456'.",  
  "instance": "/point/SNZ123456"  
}

404 Not Found​

  • Status Code: 404 Not Found
  • Description: The server could not find the requested resource. For example, the locationId provided in the URL path does not exist or was not provided.
  • User Action: Check the resource identifier in your request (e.g., locationId) to make sure it is correct.

Example Response:

{  
  "type": "https://developer.metservice.com/docs/error-handling/#not-found",  
  "title": "Resource Not Found",  
  "status": 404,  
  "detail": "The location 'Sii000000' does not exist.",  
  "instance": "/point/Sii000000"  
}

429 Rate Limit Exceeded​

  • Status Code: 429 Too Many Requests
  • Description: You have sent too many requests in a given amount of time and have exceeded your rate limit.
  • User Action: Stop sending requests and wait before attempting again. Consider implementing a retry logic with an exponential backoff strategy. For full details, please see our Platform Limits page.

Example Response:

{  
  "type": "https://developer.metservice.com/docs/error-handling/#rate-limit-exceeded",  
  "title": "Rate Limit Exceeded",  
  "status": 429,  
  "detail": "You have exceeded the request rate limit. Please try again later."  
}

500 Internal Server Error​

  • Status Code: 500 Internal Server Error
  • Description: An unexpected error occurred on the server that prevented it from fulfilling the request.
  • User Action: This indicates a problem with the API itself. Your code should implement a retry logic with an exponential backoff strategy. If the error persists, check the MetService status page for known issues.

Example Response:

{  
  "type": "https://developer.metservice.com/docs/error-handling/#internal-server-error",  
  "title": "Internal Server Error",  
  "status": 500,  
  "detail": "An unexpected error occurred on the server."  
}

503 Service Unavailable​

  • Status Code: 503 Service Unavailable
  • Description: The service is temporarily unable to handle the request, usually due to maintenance or transient overload.
  • User Action: Retry after a short delay using an exponential backoff strategy. If the problem persists, check the MetService status page for known issues.

Example Response:

{  
  "type": "https://developer.metservice.com/docs/error-handling/#service-unavailable",  
  "title": "Service Unavailable",  
  "status": 503,  
  "detail": "The service is temporarily unavailable. Please try again shortly."  
}