Errors and troubleshooting

If your first request fails, a build never finishes, or Adobe rejects a write, this is the page to use. ReactorSDK raises typed errors and leaves enough room for application-level retry and polling logic, which makes it easier to troubleshoot problems without digging through raw Faraday responses.

Typed error hierarchy

All SDK errors inherit from ReactorSDK::Error.

Attribute	Description
AuthenticationError	Raised when Adobe IMS token fetch or validation fails.
AuthorizationError	Raised when the token is valid but does not have permission for the requested Launch resource.
ResourceNotFoundError	Raised for `404` responses.
UnprocessableEntityError	Raised for validation-style `400` and `422` responses and includes `validation_errors`.
RateLimitError	Raised for `429` responses after retries are exhausted and may include `retry_after`.
ServerError	Raised for `5xx` failures after retries are exhausted.
ParseError	Raised when a response body cannot be parsed as valid JSON.
ConfigurationError	Raised when required configuration is missing or blank.

Rescue and retry patterns

Rescue narrowly where you have a concrete recovery path, then let broader boundaries handle everything else.

Operational rescue block

# LB123 = library ID.
# RL123 = rule ID.
# Try one write operation that may fail for operational reasons.
begin
  # Attach the rule to the target library.
  client.libraries.add_rules("LB123", ["RL123"])
rescue ReactorSDK::ResourceNotFoundError => error
  # The library ID or rule ID did not resolve in Adobe.
  Rails.logger.warn("Missing resource: #{error.message}")
rescue ReactorSDK::UnprocessableEntityError => error
  # Adobe accepted the request shape but rejected the payload content.
  Rails.logger.error("Validation failed: #{error.validation_errors.inspect}")
rescue ReactorSDK::RateLimitError => error
  # Back off using Adobe's suggested wait time when available.
  sleep(error.retry_after || 60)
  # Re-run the write after waiting.
  retry
rescue ReactorSDK::Error => error
  # Capture any other SDK-level failure and let the caller decide what to do next.
  Rails.logger.error("Unhandled ReactorSDK failure: #{error.class} #{error.message}")
  raise
end

ReactorSDK already performs low-level retries for 429 and common 5xx statuses. Application code should focus on business-level retries such as job rescheduling or build polling loops.

Polling and promotion jobs

Library publication is a good example of where operational orchestration belongs in your application rather than inside the SDK itself.

Assign the environment.
Trigger the build.
Poll until the build succeeds or fails.
Transition the library through submitted, approved, and published states.

Publish flow skeleton

# library_id = Adobe library ID you plan to publish.
# environment_id = Adobe environment ID that receives the build.
# Attach the library to an environment before building.
client.libraries.assign_environment(library_id, environment_id)
# Trigger a new build for that library.
build = client.libraries.build(library_id)

# Poll until Adobe marks the build as succeeded or failed.
loop do
  # Refresh the build status from Reactor.
  build = client.builds.find(build.id)
  # Exit the polling loop once the build reaches a terminal state.
  break if build.succeeded? || build.failed?
  # Wait before polling again.
  sleep 30
end

# Stop the workflow if the build failed.
raise "Build failed" if build.failed?

# Move the library through Adobe's workflow states in order.
client.libraries.transition(library_id, state: "submitted")
client.libraries.transition(library_id, state: "approved")
client.libraries.transition(library_id, state: "published")

Troubleshooting checklist

When something is not working, check these first:

Confirm your Adobe credentials can successfully list companies.
Confirm the credential set actually has access to the property or resource you are querying.
Double-check IDs such as PR..., RL..., LB..., and EN... before assuming the SDK is wrong.
Turn on a logger temporarily if you need to see request flow.
For publish workflows, verify environment assignment and build status before attempting transitions.