Connection errors

When a call to a connection is refused, you get an error with a code you can test for. Most of them are not bugs. They are ordinary states, like "nobody has connected yet", and the right response is a friendly screen.

The shape of an error

Every error from the platform has this body:

{
  "error": {
    "code": "connection_required",
    "message": "This person has not connected Google Sheets for this tool yet.",
    "how_to_fix": "Send the person to connect_url. It is one page and one consent; they come back and the call works.",
    "connect_url": "(the page to send them to)",
    "connection": "sheet"
  }
}

message says what happened. how_to_fix says what to do. Some errors add extra fields, such as connect_url and connection.

In the SDK the call throws a PlatformError. It has .status, .code, .message, .howToFix, .requestId, .details (the extra fields) and .connectUrl (the same as details.connect_url).

import { PlatformError } from '@cohostly/sdk'

try {
  await platform.connections.agenda.get({ path })
} catch (e) {
  if (e instanceof PlatformError && e.code === 'connection_required') return res.redirect(e.connectUrl)
  throw e
}

reply = requests.get(url, headers=headers, timeout=35)
if reply.status_code >= 400:
    error = reply.json()["error"]
    if error["code"] == "connection_required":
        return redirect(error["connect_url"])

Through the official Google client the error arrives as the library's own HTTP error, with the platform's body in response.data, so read e.response.data.error.code. The Microsoft client raises its own error type.

When the provider itself answers with an error, its status and body come back unchanged. The code is then the provider's, not one from this page.

<name> below is the name of your connection and <Provider> is the provider's display name, such as Google Workspace.

Normal states

These are the ones to design for. Each should lead to a button or a plain sentence.

Mistakes in your app

These mean something in your code or manifest is off. Fix it and try again.

Size, speed and time

The SDK already retries 429, 502, 503 and 504 for you (twice more). It does not retry 403, 409 or 410. See limits.

Approvals

A held write is not an error. It is a 202 with an approval_id. See holding writes for approval.

The error says why in reason, with its own message and status:

If the header is not an approval id at all, the status is 400 and the message is X-Platform-Approval-Id is not an approval id. The fix then reads: send the approval_id the 202 answer gave you.

Platform setup and odd ones

Errors from the SDK itself

These come from the SDK, before or instead of an answer from the platform.

In what order a call is checked

When a call fails, ask which check stopped it. They run in this order:

1. The connection is declared in your manifest (connection_not_declared).
2. The provider is one the platform offers (unknown_provider).
3. A path follows the name (missing_path).
4. For user mode, the visitor is known (caller_unknown).
5. A grant exists (connection_required or no_grant).
6. The grant's provider matches the manifest (provider_mismatch).
7. The connection is not disconnected or in need of reconnecting (connection_revoked, connection_needs_reauth).
8. The path is clean (path_refused).
9. Some effective permission allows the method and path (permission_not_granted, call_not_allowed).
10. The call is within the files the grant is limited to (outside_grant).
11. The body is small enough (request_too_large).
12. The connection is under its rate limit (connection_rate_limited).
13. If writes are held, the write waits (202), or the approval is checked (approval_not_valid).
14. The call goes to the provider.

Good to know The contract file made by cohostly types lists only nine of these codes. This page has the full list.

Next: limits. More fixes are in troubleshooting.