API Reference

HTTP Response Codes

The Aurora API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, authentication failed, etc.). Codes in the 5xx range indicate an error with Aurora's servers (these are rare).

Here is a more detailed summary of some of the codes:

  • 200 Success: The request was successfully processed.

  • 400 Bad Request: The request could not be processed due to a formatting error.

  • 401 Unauthorized: The API caller could not be authenticated. This may indicate a missing or incorrect token.

  • 403 Forbidden: The provided authentication token was successfully authenticated but not authorized to perform the intended action.

  • 404 Not Found: The request was partially processed. The provided authentication token was successfully authenticated and authorized, but the object/resource referenced does not exist or belongs under another tenant. This can also occur when IDs from other environments are used or when users have deleted certain resources such as a design or project.

  • 405 Method Not Allowed: The request URL or method is invalid. This usually indicates an incorrect URL path or HTTP verb.

  • 409 Conflict: The request was partially processed. The requested resource is currently in use, and could not be accessed. This usually occurs because an operation is in progress. Please wait a moment then try again.

  • 422 Unprocessable Entity: The request could not be processed. Usually, this indicates one or more mandatory parameters that are missing, such as keys. Please check the URI and payload of the API call.

  • 429 Too Many Requests: The request could not be processed. The client exceeded Aurora's API rate limit. To guard against bursts of incoming traffic and help maximize its stability, Aurora limits the number of requests received by the API within any given minute. Our default rate limit is 90 requests per minute. The rate limit is applied to all requests sent with the same API key. Please check the response body and/or the Retry-After response header for an indication when the next API call will be allowed. Note that most clients who run into the throttling limit run polling processes. We recommend the usage of webhooks. Please contact your Aurora account representative to discuss your specific needs. We are happy to help design a workflow that works for your business.

  • 5XX Internal Error: Some internal error occurred on our server. Please contact [email protected] or your dedicated support engineer.

Error Message Formats

When you receive a 4XX error, the response body may take several formats. We are working on unifying this format so it's more user-friendly. Until then, there are four formats you may encounter; each API's page includes the error responses and formats you can expect. Several of our APIs may return multiple formats from those below for a 422 response. Be sure to check the Responses section at the bottom of the endpoint's documentation; the Examples section on the right will only include one example body.

  • Empty response body: For most 404 Not Found responses, we return an empty body, so there's nothing to parse. This will not appear in the Examples list on the right side of the API page because there is no body.

  • Simple error format: {"error": "some error occurred"}
    Note: there may have been other errors that were truncated.

  • Comma-separated error format: {"error": "some error occurred, some other error occurred"}

  • Error hash format: {"error": {"field": ["some error occurred", "some other error occurred"], "another_field": ["yet another error occurred"]}}