API errors
When a request to the SharePoint Fax API fails, the response is JSON of type application/problem+json with the fields type, title, status, code and requestId. The type is a link to the matching section below, and code is the stable value to branch on; title is for people and may change. If you contact support, quote the requestId.
Signed-in users can find setup steps in the developer guide.
- invalid_api_key
- api_disabled
- ip_not_allowed
- insufficient_scope
- rate_limited
- number_not_allowed
- pdf_invalid
- allowance_exhausted
- idempotency_conflict
- idempotency_key_required
- invalid_cursor
- length_required
- not_found
- validation_failed
- limit_reached
- forbidden
- unavailable
- internal
invalid_api_key
HTTP status 401
What it means
The Authorization header is missing, or the key in it is wrong, expired or revoked.
What to do
Send the key as "Authorization: Bearer <key>". If the key was revoked or has expired, create a new one in Settings, API keys.
api_disabled
HTTP status 403
What it means
The API is turned off for this workspace.
What to do
Ask a workspace owner to turn the API on in Settings, then retry.
ip_not_allowed
HTTP status 403
What it means
The key has an address allow-list and this request came from an address that is not on it.
What to do
Send the request from an allowed address, or ask a workspace owner to update the key's allowed addresses.
insufficient_scope
HTTP status 403
What it means
The key is valid but was not given the permission this request needs, such as sending or reading faxes.
What to do
Use a key that has the required scope, or create one with it. Do not retry with the same key.
rate_limited
HTTP status 429
What it means
This key sent too many requests in a short time.
What to do
Wait for the number of seconds in the Retry-After header, then retry. Spread bursts of requests over time.
number_not_allowed
HTTP status 403
What it means
The key is restricted to certain fax numbers or groups, and this request used one it may not use.
What to do
Use a number or group the key is allowed to use, or ask a workspace owner to widen the key's access.
pdf_invalid
HTTP status 422
What it means
The document is not a PDF we can send. It must be a PDF of 1 to 200 pages, up to 20 MiB, without a password.
What to do
Fix or re-export the PDF so it meets those limits and send it again with a new Idempotency-Key.
allowance_exhausted
HTTP status 403
What it means
The workspace has used up its page allowance for the current period.
What to do
Ask a workspace owner to add pages or change the plan. Retrying will not help until then.
idempotency_conflict
HTTP status 409
What it means
This Idempotency-Key was already used for a different request.
What to do
Use a new, unique Idempotency-Key for each distinct request. Reuse a key only to retry the exact same request.
idempotency_key_required
HTTP status 400
What it means
Sending a fax requires an Idempotency-Key header, and it was missing or malformed.
What to do
Add an Idempotency-Key header of 8 to 128 letters, digits, hyphens or underscores. Keep it the same when retrying.
invalid_cursor
HTTP status 400
What it means
The pagination cursor is malformed, expired, or was issued to a different key.
What to do
Start again from the first page without a cursor, and pass back the cursor exactly as the previous response returned it.
length_required
HTTP status 411
What it means
The request has a body but no Content-Length header.
What to do
Send the request with a Content-Length header instead of chunked transfer encoding.
not_found
HTTP status 404
What it means
The fax, number or other item you asked for does not exist, or this key cannot see it.
What to do
Check the identifier. Items from another workspace are reported as not found.
validation_failed
HTTP status 422
What it means
The request is well formed but its contents are not acceptable, for example a missing or invalid field.
What to do
Check the request against the OpenAPI description, correct it, and send it again.
limit_reached
HTTP status 409
What it means
A workspace limit was reached, such as a maximum number of items of this kind.
What to do
Remove something you no longer need, or ask a workspace owner about raising the limit.
forbidden
HTTP status 403
What it means
The request is understood but is not allowed for this key or workspace.
What to do
Do not retry unchanged. Check the key's permissions and the workspace settings, or contact support.
internal
HTTP status 500
What it means
Something went wrong on our side.
What to do
Retry once after a short wait. If it keeps happening, contact support and quote the requestId from the response.