Errors

One shape for every failure, and the codes to branch on.

The shape

Every failure has this shape. Branch on code, which is stable; the error text may be reworded at any time and is written to be shown to a vet.

errorstringrequired

Human-readable explanation, safe to display.

codeErrorCoderequired

One of 19 values, listed under ErrorCode.

Codes

• unsupported_language
• unsupported_note_format
• invalid_request
• missing_idempotency_key
• idempotency_key_reused
• invalid_client
• invalid_code
• invalid_token
• connection_revoked
• partner_disabled
• subscription_inactive
• audio_too_large
• audio_unreadable
• note_not_found
• rate_limited
• internal_error
• audio_unavailable
• transcription_failed
• note_generation_failed

Stable identifier for a failure. New codes may be added within /v1, so treat one you do not recognise as a generic failure rather than failing hard.

internal_error is ours, not yours: something on our side failed before we could judge your request. Retry the same call shortly; nothing has been consumed.

The last three are the ways a consult can fail after it was accepted, and what you should do differs for each:

audio_unavailable: the recording could not be read back for processing. Ours to fix, not yours.

transcription_failed: speech recognition failed after internal retries. Retrying will not help, because it has already been retried. Have the vet check the microphone and input device before the next consult.

note_generation_failed: the transcript survived and is on the note. Show it to the vet so they can write the record themselves. Transport failures are already retried inside the model client, so one that reaches you has survived those and will not clear on its own.

Shared responses

Server Error

Something failed on our side before your request could be judged. Retry shortly: nothing was consumed, and no note was created.

{
  "error": "Could not verify that connection. Try again shortly.",
  "code": "internal_error"
}

Bad Request

The request was rejected. Do not retry unchanged.

invalid_request

{
  "error": "client_id, client_secret and code are required",
  "code": "invalid_request"
}

unsupported_language

{
  "error": "Only English notes are available on this API.",
  "code": "unsupported_language"
}

missing_idempotency_key

{
  "error": "An Idempotency-Key header is required.",
  "code": "missing_idempotency_key"
}

Unauthorized

The token is missing, malformed, or no longer valid. connection_revoked means the vet disconnected or left the practice, so clear the stored token and send them through the connect flow again.

partner_disabled is different and reconnecting will not fix it: your integration itself is switched off, and every token you hold stops at once. Stop retrying and contact us.

invalid_token

{
  "error": "That connection token is not valid.",
  "code": "invalid_token"
}

connection_revoked

{
  "error": "That vet is no longer connected to WisePaws.",
  "code": "connection_revoked"
}

partner_disabled

{
  "error": "This integration is no longer enabled. Contact WisePaws.",
  "code": "partner_disabled"
}

Note Not Found

No note with that id belongs to this connection.

{
  "error": "No note was found with that id.",
  "code": "note_not_found"
}

Rate Limited

On the note endpoints the ceiling is per connection, and submitting a recording is held far tighter than polling, which the contract asks you to do every 3 seconds. On /v1/connections/exchange, which has no connection yet, it is per source address. A platform-wide backstop sits above both; it is sized so that normal traffic never reaches it. Back off and respect Retry-After.

{
  "error": "Too many requests. Retry shortly.",
  "code": "rate_limited"
}