Errors

Codes and format for both expected and unexpected error responses

An error message from Atlas is a json structure with the following fields:

KeyDescriptionPresent when
message
String
A message summarizing the problemAlways
validation_errors
Array of strings
A list of validation errors when invalid input data is providedValidation failure
eventID
String
A reference to an internally tracked errorAn unexpected error is encountered

Error codes

Atlas uses conventional and commonly encountered http status codes. 2xx codes indicate success; 4xx are expected errors likely resulting from invalid input or authentication failure; 5xx indicate a problem with the Atlas API.

Http response codeDescription
200
OK
Operation completed successfully
201
Created
An object or list of objects were successfully created
400
Bad request
The request was unacceptable due, perhaps due to validation or a missing parameter
401
Unauthorized
Authentication failed. Incorrect or invalid API key, ID token or username / password
403
Forbidden
The authenticated user doesn't have permissions to complete the operation
404
Not found
The resource or endpoint doesn't exist
429
Too many requests
This is a rate limiting error. Too many requests to the API were made within a time window. Your application should throttle back requests using exponential backoff when this error is encountered.
503
Service unavailable
Atlas is unavailable due to routine maintenance. Try again later.
502, 504The API is experiencing excessive latency or encountering load balancing errors. Your application should backoff exponentially.
500 or other 5xxAn unexpected error was encountered; the Atlas team has been notified

Examples

An example might look something like this

A basic error response message from Atlas is a json response that looks like this:

{
  "message": "Error message here"
}

Validation errors provide additional information when invalid data is provided. In this case the validation_errors key is furnished, like this:

{
  "message": "Error message here",
  "validation_errors": [
    "ID is required",
    "Name is required",
  ]
}

When an unexpected error is encountered it's automatically reported to our engineering team. When this happens the event ID our team receives is made available, which you may find useful in communicating with support. For example:

{
  "eventID":"c3cc54b96c554b378adcd1d27da090c2",
  "message":"Failed to do something"
}