[secretpray]

Depends on #3. Authentication, error handling, retries and logging of the transport layer.

Authentication

• Authorization: Bearer <api_key>. A value that already starts with Bearer and surrounding whitespace are normalized
• Each endpoint declares whether it needs a key:
  • required: AuthenticationError is raised before the request when no key is configured
  • optional: the key is sent when present (machine listings, which are fresher with a key)
  • none: the key is never sent
• A 401 for a key that does not start with octa_ak_ adds a hint on where to create an API key

Base URL

• The default base URL is https://api-dev.octa.space
• Trailing slashes are stripped, and a path prefix in base_url is kept

Errors

Status	Class
400, 422	ValidationError
401	AuthenticationError
403	PermissionError
404	NotFoundError
409	ConflictError (new)
429	RateLimitError
503	ServiceUnavailableError
other 5xx	ServerError (BadGatewayError 502, GatewayTimeoutError 504)

• The error message is the API's message, falling back to the body text, cut to 512 characters
• ApiError#retry_after, #rate_limit, #body, #request_id
• A 2xx response that is not JSON (for example from a proxy) raises ApiError, not a parsing exception

Rate limits and retries

• RateLimit-Limit/Remaining/Reset → OctaSpace::RateLimit; the latest value is client.rate_limit
• Retry-After is read as seconds (a fraction is rounded up) or as an HTTP date
• Only GET requests and session stop are retried, on network errors and on 429/502/503/504
  • Backoff with jitter, capped at max_retry_interval (10 s)
  • Retry-After is honoured up to max_retry_after (60 s); a longer wait, such as the restart cooldown, is raised to the caller
• Starting and restarting sessions are never retried
• Failover across base_urls applies only to GET on network errors. A request that changes state is never sent to a second host; previously a POST could be repeated on the next URL.

Other

• Empty 202/204 bodies are accepted
• One reused connection per URL (previously a new connection per request when there were several URLs)
• One log line per request ([OctaSpace] GET https://… -> 200 (12 ms)). Headers and bodies are never logged; previously Faraday's logger printed the Authorization header. on_request no longer receives headers.
• faraday-retry dependency removed

Verification

• bundle exec rake test on Ruby 3.3, 3.4 and 4.0: 0 failures. New tests cover authentication modes, the retry policy, Retry-After limits, GET-only failover, 202/204, invalid JSON, the key hint, and that the key never reaches logs or hooks
• standardrb: clean