Skip to main content

Error response format

Orb's error response format follows RFC7807. Each error response includes:

  • status: Same as the HTTP status code
  • title: Brief description of the error message
  • type: URI that always links to this document for further reference
  • detail: Human readable description providing more insight into the error

Note that error responses may include other keys specific to the error.

{
"detail": "Could not find a resource of type Plan with identifier: DBhwNcMNfYgeBpn.",
"status": 404,
"title": "A specified resource was not found.",
"type": "https://docs.withorb.com/reference/error-responses#404-resource-not-found"
}

The following table describes the error types. If you are processing an error programatically, consider using the type URI along with the status code. The type URI is a stable identifier for the class of error.

TitleStatus codeDescriptiontype uri
Authentication failure401Your request did not provide a valid or well-formatted API key.https://docs.withorb.com/reference/error-responses#401-authentication-error
Request validation error400A request that fails validation will return human-readable information about what went wrong. The error response for this includes an array of validation_errors.https://docs.withorb.com/reference/error-responses#400-request-validation-errors
Duplicate resource creation400Returned when the ID passed to the creation request already exists.https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation
Resource not found404This is returned when a provided identifier does not map to a resource that is accessible by the current account.https://docs.withorb.com/reference/error-responses#404-resource-not-found
Feature not available404Returned when the endpoint or feature is behind a feature flag on the server-side and is unavailable for current use.https://docs.withorb.com/reference/error-responses#404-feature-not-available
URL not found404Returned when the requested URL was not found on the server.https://docs.withorb.com/reference/error-responses#404-url-not-found
Resource conflict409Returned when the request conflicts with another concurrent request that is using the same idempotency key or if the same idempotency key has been used for a request with different parameters. Note that this may also be returned from specific endpoints that require a consistent view of a resource (e.g. the credits ledger) when concurrent requests attempt to modify it. Please retry these errors, as they're expected to be transient in these cases.https://docs.withorb.com/reference/error-responses#409-resource-conflict
Too many requests429Returned when the request rate exceeds the limit.https://docs.withorb.com/reference/error-responses#429-too-many-requests
Internal Server error500This is an internal server crash. The Orb team has been notified!https://docs.withorb.com/reference/error-responses#500-internal-server-error