Overview

Alloy 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, creating an item failed, etc.).
  • Codes in the 5xx range indicate an error with Alloy’s servers (these are rare).

HTTP status code summary

Code Description
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn’t exist.
409 - Conflict The request conflicts with another request.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on Alloy’s end. (These are rare.)

Error types

Error type Description
api_connection_error Failure to connect to Alloy’s API.
api_error API errors cover any other type of problem (e.g., a temporary problem with Alloy’s servers), and are extremely uncommon.
authentication_error Failure to properly authenticate yourself in the request.
invalid_request_error Invalid request errors arise when your request has invalid parameters.
rate_limit_error Too many requests hit the API too quickly.
validation_error Errors triggered by our client-side libraries when failing to validate fields (e.g., when a job number or date is invalid or incomplete).

We have developed a comprehensive list of error categories. They have been named to be self exlanatory.

  • AIdInvalid
  • AlloyTaskConflict
  • AlloyTaskNotFound
  • AqsInternalFailure
  • AqsInvalidQuery
  • AuthLogNotFound
  • BadRequest
  • BsonDeserializationFailed
  • BsonSerializationFailed
  • BulkActionNotFound
  • CacheGetFailed
  • CacheStoreFailed
  • CardCreateForbidden
  • CardDeleteForbidden
  • CardEditForbidden
  • CardNotFound
  • CardPermissionAlreadyPresent
  • CardQueryInvalid
  • CardQueryNotFound
  • CardReadForbidden
  • CardSignatureMismatch
  • CircularDependency
  • CustomerCreateForbidden
  • CustomerDeleteForbidden
  • CustomerEditForbidden
  • CustomerNotEnabled
  • CustomerNotFound
  • CustomerReadForbidden
  • CustomerSettingNotFound
  • CustomerSignatureMismatch
  • CustomerUnauthorized
  • CustomerUserAlreadyExists
  • CustomerUserNotFound
  • DatabaseConnection
  • DatabaseDocumentUniqueConstraint
  • DatabaseNestedError
  • DatabaseNotFound
  • DatabaseParameterInvalid
  • DatabaseTransientError
  • DatabaseUniqueConstraint
  • DefaultUserAlreadyExists
  • DesignCreateForbidden
  • DesignDeleteForbidden
  • DesignEditForbidden
  • DesignInterfaceCreateForbidden
  • DesignInterfaceDeleteForbidden
  • DesignInterfaceEditForbidden
  • DesignInterfaceForbidden
  • DesignInterfaceNotFound
  • DesignInterfacePermissionAlreadyPresent
  • DesignInterfaceReadForbidden
  • DesignInterfaceSignatureMismatch
  • DesignInvalidGeometry
  • DesignNotFound
  • DesignPermissionAlreadyPresent
  • DesignReadForbidden
  • DesignSignatureMismatch
  • DocumentDeleteFailed
  • DocumentEditFailed
  • DodiAttributeCodeUniqueViolated
  • DodiAttributeCreateForbidden
  • DodiAttributeDeleteForbidden
  • DodiAttributeEditForbidden
  • DodiAttributeInUse
  • DodiAttributeLinkItemNotFound
  • DodiAttributeNotFound
  • DodiAttributeNotInDesign
  • DodiAttributeOptionConstraintViolated
  • DodiAttributeOptionInvalid
  • DodiAttributeOptionNotFound
  • DodiAttributeOptionsMalformed
  • DodiAttributePermissionAlreadyPresent
  • DodiAttributeReadForbidden
  • DodiAttributeReadonlyViolated
  • DodiAttributeRelationConstraintViolated
  • DodiAttributeRequiredViolated
  • DodiAttributeTypeViolated
  • DodiAttributeUniqueViolated
  • DodiAttributeWriteForbidden
  • DodiConstraint
  • DodiNotFound
  • EngineInitialization
  • EngineNotInitialized
  • ExportFormatNotSupported
  • ExportTaskFileNotFound
  • FileConflict
  • FileDeletionFailed
  • FileDownloadFailed
  • FileGenericError
  • FileListFailed
  • FileNotFound
  • FileUnauthorized
  • FileUploadFailed
  • FolderForbidden
  • FolderNotFound
  • ForgeAccessForbidden
  • ForgeException
  • ForgeModuleNotFound
  • ForgeParameterInvalid
  • ForgeParameterNotFound
  • ForgeReferenceNotFound
  • ForgeTaskNotFound
  • GeoJsonSridNotSupported
  • GucInvalid
  • ImportConstraintViolated
  • ImportConversion
  • ImportDeleteForbidden
  • ImportFileBadFormat
  • ImportFileNotSupported
  • ImportNotFound
  • ImportReadForbidden
  • ImportRecordNotFound
  • ImportSignatureMismatch
  • ImportWrongState
  • IncorrectConfiguration
  • InternalError
  • ItemCreateForbidden
  • ItemDeleteForbidden
  • ItemEditForbidden
  • ItemGeometryConstraintViolated
  • ItemLogNotFound
  • ItemNotFound
  • ItemParentsConstraintViolated
  • ItemReadForbidden
  • ItemSignatureMismatch
  • ItemSyncForbidden
  • ItemVersionNotFound
  • JsonDeserializationFailed
  • JsonSerializationFailed
  • LayerClusterTileNotFound
  • LayerCreateForbidden
  • LayerDeleteForbidden
  • LayerEditForbidden
  • LayerNotFound
  • LayerPermissionAlreadyPresent
  • LayerReadForbidden
  • LayerSignatureMismatch
  • LayerStyleMalformed
  • LayerStyleNotFound
  • LayerTileRequestMalformed
  • LogNotFound
  • MasterSettingNotFound
  • MeshCreateForbidden
  • MeshDeleteForbidden
  • MeshEditForbidden
  • MeshNotFound
  • MeshPermissionAlreadyPresent
  • MeshReadForbidden
  • MeshSignatureMismatch
  • MissingRequestHeader
  • MissingRequestParameter
  • ModelValidationFailed
  • ModuleCreateForbidden
  • ModuleDeleteForbidden
  • ModuleEditForbidden
  • ModuleNotFound
  • ModuleSignatureMismatch
  • MongoBackupFailed
  • MongoRestoreFailed
  • ReadonlyUserNotFound
  • ReportSignatureMismatch
  • ReportWrongDesign
  • RouteCouldNotBeGenerated
  • RouteItemGeometry
  • RouteNotFound
  • RouteOsrmException
  • ScheduleNotFound
  • ScheduleSignatureMismatch
  • SystemLogNotFound
  • SystemUnderMaintenance
  • ThumbnailNotFound
  • UpgradeInternalError
  • UserBadPassword
  • UserBotCreateForbidden
  • UserBotNotFound
  • UserCreateForbidden
  • UserDeleteForbidden
  • UserDisableForbidden
  • UserEditForbidden
  • UserForbidden
  • UserGroupAddingExistentUser
  • UserGroupCreateForbidden
  • UserGroupDeleteForbidden
  • UserGroupEditForbidden
  • UserGroupNotFound
  • UserGroupRemovingNonExistentUser
  • UserGroupSignatureMismatch
  • UserInvalidResetToken
  • UserNotFound
  • UserPasswordResetForbidden
  • UserReadForbidden
  • UserSessionInvalid
  • UserSessionNotFound
  • UserSignatureMismatch
  • UserUnauthorized
  • WebhookCreation
  • WebhookForbidden
  • WebhookGeneric
  • WebhookRegistrationNotFound
  • WebhookTriggerFailed
  • WorkflowActionNotFound
  • WorkflowCreateForbidden
  • WorkflowDeleteForbidden
  • WorkflowEditForbidden
  • WorkflowLogNotFound
  • WorkflowMalformed
  • WorkflowNotFound
  • WorkflowPermissionAlreadyPresent
  • WorkflowReadForbidden
  • WorkflowSignatureMismatch