Errors, limits and troubleshooting

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.
403	The business's plan does not include the API, or a plan limit is reached (for example knowledge sources).
404	The action, endpoint or knowledge key does not exist for this business.
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.

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
Connected actions per business	10
Action parameters	8, flat: string, number, integer, boolean
Action description	20 to 600 characters
Action answer time	5 seconds
Action response	16 KB read; first 4,000 characters reach the Secretary
Action calls per customer message	2
Knowledge content	20 to 8,000 characters per key
Knowledge sources	3 on Pro, 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 the URL change? A new URL switches it off until the owner approves it.
• Does the description match how customers ask? If customers say "pay" and your description only says "compensation", 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? Actions are not considered on routine replies like those.

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. Not your endpoint's fault; check enum values and types.

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.