ahlan hamad

Errors

Errors are returned as application/problem+json (RFC 9457). Branch on code, never on title — titles are for people and may be reworded. Every response, success or error, carries anX-Request-Id; include it when you contact support.

{
  "type": "https://ahlanhamad.com/developers/errors#insufficient_scope",
  "title": "This key does not have the payroll:read scope",
  "status": 403,
  "code": "insufficient_scope",
  "request_id": "req_01J9…"
}
CodeStatusMeaningWhat to do
invalid_request400A query parameter, the JSON body or the cursor is malformed.Fix the request. Retrying unchanged will fail the same way.
unauthenticated401The key is missing, malformed, revoked, or the wrong kind for the company (an ah_test_ key on a live company or the reverse).Check the Authorization header and the key's mode. Ask the customer for a new key if it was revoked.
insufficient_scope403The key is valid but was not granted the scope this endpoint needs.Ask the customer to create a key with the scope named in the error title.
api_not_enabled403The Partner API is not enabled for this company yet (it opens to companies in stages).Build against a sandbox company, and contact support to enable a pilot customer.
not_found404No such resource in this company, or it is not visible to partners (a draft payroll run, for example), or no such endpoint.Check the id and path.
conflict409The request conflicts with the current state — for example redelivering to a disabled webhook endpoint.Resolve the state (re-enable the endpoint) and retry.
payload_too_large413More than 500 events in one attendance-ingest request, or a body over 1 MB there; a JSON body over 64 KB on the other JSON endpoints.Split the batch.
validation_failed422The body is well-formed JSON but fails validation; errors[] lists each field.Fix the fields listed in errors[].
read_only403The company's workspace is read-only because its trial or subscription has lapsed, so the API cannot change anything in it. Reads still work.Ask the customer to reactivate their plan, then retry.
attestation_required403Payslips need the company's payslip attestation (and, for staff in Kuwait, Oman or Jordan, their consent), and are not available on live companies until terms that allow them are in force. The title says which.Ask the company to create a new key with the payslip attestation, or build against a sandbox company.
confirmation_required403This key has not been switched on for AI assistants (the MCP server). Someone at the company must confirm once that the AI vendor becomes their processor and the data leaves the GCC.Ask the company to turn the key on under Integrations → API keys → AI assistants.
rate_limited429Too many requests for this key (600 per minute by default).Wait for Retry-After seconds, then retry. Watch X-RateLimit-Remaining.
internal_error5xxSomething failed on our side.Retry with backoff. If it persists, email support with the request_id.