arsduo/koala · error · Koala::Facebook::ServerError

ServerError.new(response.status, response.body)

Error message

ServerError.new(response.status, response.body)

What it means

fetch_token_string is the shared worker behind every server-side token call (get_access_token_info, get_app_access_token_info, exchange_access_token_info, generate_client_code). It hits /oauth/<endpoint> over SSL and raises Koala::Facebook::ServerError (an APIError carrying http_status and response_body) whenever Facebook responds with status 500 or above. A 5xx here means the failure sits on the Facebook side or in front of it (outage, rate-limit infrastructure, deprecated API version), not in your OAuth parameters.

Source

Thrown at lib/koala/oauth.rb:311

            else
              raise
            end
          end

          components.merge(token_info) if token_info
        else
          Koala::Utils.logger.warn("Signed cookie didn't contain Facebook OAuth code! Components: #{components}")
          nil
        end
      end

      def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
        response = Koala.make_request("/oauth/#{endpoint}", {
          :client_id => @app_id,
          :client_secret => @app_secret
        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options))

        raise ServerError.new(response.status, response.body) if response.status >= 500
        raise OAuthTokenRequestError.new(response.status, response.body) if response.status >= 400

        response.body
      end

      # base 64
      # directly from https://github.com/facebook/crypto-request-examples/raw/master/sample.rb
      def base64_url_decode(str)
        str += '=' * (4 - str.length.modulo(4))
        Base64.decode64(str.tr('-_', '+/'))
      end

      def server_url(type)
        url = "https://#{Koala.config.send(type)}"
        if version = Koala.config.api_version
          "#{url}/#{version}"
        else
          url

View on GitHub (pinned to 47d052063e)

Solutions

Check Facebook platform status before debugging code; 5xx from /oauth endpoints usually tracks a known incident.
Retry with capped exponential backoff and jitter; these responses are transient by nature.
Verify Koala.config.api_version points to a live Graph API version and upgrade the Koala gem if needed.
Log e.http_status and e.response_body to confirm which endpoint and status are failing.

Example fix

// before
token = @oauth.exchange_access_token(old_token)

// after
attempts = 0
begin
  attempts += 1
  token = @oauth.exchange_access_token(old_token)
rescue Koala::Facebook::ServerError => e
  raise if attempts >= 3
  sleep(2 ** attempts + rand(2))
  retry
end

Defensive patterns

Strategy: retry

Try / catch

begin
  @oauth.exchange_access_token(token)
rescue Koala::Facebook::ServerError => e
  # 5xx: transient; this endpoint is idempotent so retry with backoff
  retry_with_backoff(max_attempts: 3) { @oauth.exchange_access_token(token) }
end

Prevention

Wrap token calls in bounded retry-with-backoff for 5xx only, and cap total attempts
Do not blind-retry code redemption more than once; a 5xx can mask a success and OAuth codes are single-use
Watch Facebook platform status and Graph version deprecation notices; bump api_version before cutoffs

When it happens

Trigger: Any token endpoint call returning 5xx: get_access_token(code) or exchange_access_token(token) during a Facebook platform incident; Koala.config.api_version pinned to a Graph version Facebook has removed so /oauth/access_token starts failing; an upstream proxy returning 502 or 504 for graph.facebook.com.

Common situations: Graph API outages (check the Facebook developer status page); deprecation deadlines passing with an old Koala or an old api_version; corporate egress proxies; retry storms amplifying an incident.

Related errors

AI-assisted analysis of arsduo/koala@47d052063e (2026-08-23). Data as JSON: /api/errors/3e62403bda771796. Report an issue: GitHub.