Skip to main content

Error Handling

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.

The type field in the error response is a URI that links directly to the relevant error description on this page.

Common Error Types​

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": "/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"  
    }  
  ]  
}

Unauthorized​

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

Example Response:

{  
  "type": "/error-handling/unauthorized",  
  "title": "Unauthorized",  
  "status": 401,  
  "detail": "A valid API key was not provided in the 'apikey' header."  
}

Forbidden​

  • Status Code: 403 Forbidden
  • Description: The server understood the request, but is refusing to fulfill it. This means your API key is valid, but it does not have the necessary permissions to access the requested resource.
  • User Action: Verify that your API key has the necessary permissions for the resource you are trying to access. You may need to request additional access from sales@metservice.com.

Example Response:

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

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": "/error-handling/not-found",  
  "title": "Resource Not Found",  
  "status": 404,  
  "detail": "The location 'Sii000000' does not exist.",  
  "instance": "/point/Sii000000"  
}

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 for the duration specified in the Retry-After response header 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": "/error-handling/rate-limit-exceeded",  
  "title": "Rate Limit Exceeded",  
  "status": 429,  
  "detail": "You have exceeded the request rate limit. Please try again later."  
}

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": "/error-handling/internal-server-error",  
  "title": "Internal Server Error",  
  "status": 500,  
  "detail": "An unexpected error occurred on the server."  
}