Error Messages

Common error types & patterns you may encounter.

The status of API requests are indicated by standard HTTP response codes.

The response body of a failed API request will be JSON encoded, containing details about the error. The errors will be described in RFC 7807 format

See below for an example of when a request is made without an API key, which will return a status code of 401 Unauthorized:

{
  "title": "invalid-access-token"
  "detail": "The API Key provided is not valid",
  "type": "https://reference.airbyte.com/reference/errors#invalid-api-key",
  "status": "401",
}

Errors always contain at least three keys, title, detail, type.

  • title (string) - A short, human-readable title for the general error type; the title should not change for given types.
  • detail (string) - A human-readable description of the specific error.
  • type (string) - A URL to a document describing the error condition (optional, and "about:blank" is assumed if none is provided; should resolve to a human-readable document).
  • status (string) - The status code of the error, which should match the HTTP status code.

You can follow the type link for more information about the error and steps to help resolve the issue.

400 Resource Not Found

Resource Not Found is raised when the id presented in the request cannot be found for the given resource type. For instance, if a UUID of a Connection does not match a Connection in a Workspace that the Access Token has access to, then the Resource Not Found error will be raised.

401 Invalid API Key

Invalid API Key error will be raised if the API Key cannot be verified. Ensure the entire API key is copied correctly and the Authorization header is used. The Authorization headers value must also start with Bearer, followed by a space, then the token.

403 Forbidden

403 Forbidden errors can show up if you do not have a User-Agent request header set up correctly. Normally, the User-Agent is automatically set for you, but in some cases you may need to explicitly set the User-Agent with a string value of your choice. This is sometimes required when interacting with the Airbyte API through interfaces or tooling in the Python ecosystem, as these tools may not set the User-Agent for you automatically.

One such case would be when sending a request through a jupyter notebook using the python requests library.

409 Try Again Later

Try Again Later means that your request was valid, but the resource was currently busy. For instance, if a sync is already running, calling sync again will raise the Try Again Later error, as you can only have one sync running simultaneously.

422 Unprocessable Entity

Unprocessable Entity means that your request was valid, but the payload sent was not in the correct form. For instance, if you were POSTing at an endpoint to create a resource and that resource was missing a required field, an Unprocessable Entity error will be raised. The error message should include details on what was wrong with the payload sent to Airbyte.

422 Invalid Redirect URL

Invalid Redirect URL means that an invalid redirect URL was provided to us when initiating OAuth for a source or destination. If you see this error, please initiate OAuth with a valid redirect URL.

Your redirect URL should be an HTTPS URL like https://example.com.

500 Invalid Consent URL

Invalid Consent URL means that an unexpected error occurred during the generation of your OAuth consent URL. If you see this error, please reach out to the Airbyte support team and reference this page.