HTTP Response Codes

Error responses from the Weather Source APIs (i.e. not a 200 response) follow this format:

{"errorCode": int, "errorMessage": string}

An example error response follows:

{"errorCode": 401, "errorMessage": "UNAUTHENTICATED. The API key must be included as a header parameter named X-API-KEY"}

The Weather Source APIs use a set of well-defined status codes (derived from gRPC):

Response Code Description
200 OK OK is returned on success.
400 FAILED PRECONDITION Failed Precondition indicates operation was rejected because the system is not in a state required for the operation’s execution.
400 INVALID ARGUMENT Invalid Argument indicates the client specified an invalid argument. Note that this differs from Failed Precondition. It indicates arguments that are problematic regardless of the state of the system (e.g., a malformed timestamp).
400 OUT OF RANGE Out Of Range means the operation was attempted past the valid range. E.g., seeking or reading past the end of a file.

Unlike Invalid Argument, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate Invalid Argument if asked to read at an offset that is not in the range [0,2^32-1], but it will generate Out Of Range if asked to read from an offset past the current file size.

401 UNAUTHENTICATED Unauthenticated indicates the request does not have valid authentication credentials for the operation.
403 PERMISSION DENIED Permission Denied indicates the caller does not have permission to execute the specified operation. It is not used for rejections caused by exhausting some resource (Resource Exhausted). It is not used if the caller cannot be identified (Unauthenticated).
404 NOT FOUND Not Found means some requested entity was not found.
409 ABORTED Aborted indicates the operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.
409 ALREADY EXISTS Already Exists means an attempt to create an entity failed because one already exists.
429 RESOURCE EXHAUSTED Resource Exhausted indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
499 CANCELED Canceled indicates the operation was canceled (typically by the caller).
500 INTERNAL ERROR Internal Error means some invariants expected by the underlying system has been broken. If you see one of these errors, something is very broken.
500 UNKNOWN ERROR Unknown Error. An example of where this error may be returned is if a Status value received from another address space belongs to an error-space that is not known in this address space. Also, errors raised by APIs that do not return enough error information may be converted to this error.
500 DATA LOSS Data Loss indicates unrecoverable data loss or corruption.
501 NOT IMPLEMENTED Not Implemented indicates the operation is not implemented or not supported/enabled in this service.
503 UNAVAILABLE Unavailable indicates the service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
504 DEADLINE EXCEEDED Deadline Exceeded means operation expired before completion. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.