Errors, limits and troubleshooting

Every error status the API returns, every limit in one table, and what to check when an action, a webhook or pushed knowledge is not working.

Error responses

Every error has a JSON body with one sentence saying what went wrong:

{ "error": "url must be a public https address." }
Status Meaning
400 The request is invalid: a missing field, a wrong type, a bad name. The message says which.
401 The API key is missing, malformed or revoked, or the access token has expired or was revoked.
403 The business's plan does not include the API, its account is not active, or a plan limit is reached (for example knowledge sources).
404 The action, intake, endpoint or knowledge key does not exist for this business, or another key or app made it.
413 Knowledge content is longer than 8,000 characters.
429 Too many requests of this kind; try again later.
500 Something failed on Ordina's side. Retry with a short backoff.
503 Ordina could not check which key or app owns an item just now, or intakes are not available yet. Nothing was changed; retry after the Retry-After seconds.

Limits

What Limit
API keys per business 10 active
Webhook endpoints per business 20
Webhook answer time 10 seconds; retried 5 more times over about 15 hours, by a job that runs every 15 minutes
Connected actions per business 10
Action parameters 8, flat: string, number, integer, boolean
Action description 20 to 600 characters
Action answer time 5 seconds for a lookup, 10 seconds for a write
Action response 16 KB read; first 4,000 characters reach the Secretary
Lookups per customer message 2
Write requests per customer message 1, shown to the customer for a yes
Lookups per phone call 6 (write actions do not run on calls)
A write request waits for a yes 30 minutes; a yes within 1.5 seconds of it being shown is asked again
Intakes per business 5
Intake questions 1 to 12, at least one required; a select has 2 to 20 options
Intake description 20 to 500 characters
Intake responses 50 per page
Knowledge content 20 to 8,000 characters per key
Knowledge sources 5 on Business, including PDFs and websites
Knowledge pushes 120 per hour per business
List endpoints Up to 100 items per request

The Secretary never calls my action

  • Is it switched on? GET /api/v1/actions/{id} shows enabled. Only the owner can switch it on.
  • Did you change it? Any change through the API switches it off until the owner approves it again.
  • Was your key revoked, or your app disconnected? That switches off every action it registered.
  • Does the description match how customers ask? If customers say "parcel" and your description only says "shipment", add both. The description is all the Secretary sees.
  • Is a required parameter something customers rarely say? The Secretary asks for a missing required value instead of calling. Make it optional if you can answer without it.
  • Was the message just a name, a phone number or a yes? Lookups are not considered on routine replies like those. Write actions still are, because such a reply can be the detail a request was waiting for.

The Secretary says it could not check

Look at the call history (GET /api/v1/actions/{id}):

Status Likely cause
timeout Your endpoint took over 5 seconds. Watch for cold starts.
error, HTTP 4xx or 5xx Your endpoint refused or failed. A 401 or 403 often means signature verification is rejecting good requests: see Verify signatures.
error, did not return JSON An HTML error page, or an empty body.
error, larger than 16000 bytes Trim the response.
error, address cannot be fetched Your hostname resolves to a private address.
rejected The Secretary's values did not fit your schema, or a write could no longer run as confirmed (for example the action changed after the request was shown). Not your endpoint's fault; check enum values and types.
unknown A write got no answer within 10 seconds, or the connection dropped. Ordina does not retry it; look up its Idempotency-Key in your logs to see whether it went through.

Webhooks are not arriving

  • Check the endpoint is enabled and see its history in Integration, Webhooks, or press Test to send a ping.
  • Answer 2xx within 10 seconds, without a redirect. A trailing-slash redirect counts as a failure.
  • Make sure your firewall accepts requests from the internet.

Pushed knowledge is not used

  • GET /api/v1/knowledge confirms it is stored.
  • The question has to be one the text actually answers. Put the key facts early in the text, in plain sentences.
  • Too much text in total means some is not read for a given answer. Shorter, focused keys work best.

Still stuck

Email help@useordina.com with the business handle, the action name or endpoint, and the time of the request. The call id (X-Ordina-Call) or delivery id (X-Ordina-Delivery) helps us find it quickly.

Did this answer it?If not, write to help@useordina.com with your handle, or contact us. A person replies.
Contact us