MASKDocs

Integration API

Errors

Every error on /integration/ has one shape, and the code tells your program what happened.

{
  "status": "error",
  "code": "validation_failed",
  "message": "Validation failed",
  "requestId": "1df1c790-6f49-4bfb-ab3a-565f03c05160",
  "violations": [
    {"field": "institutionId", "message": "must not be null"},
    {"field": "eventTime", "message": "must be greater than 0"},
    {"field": "eventCode", "message": "must not be blank"}
  ]
}
  • Program against code. message is for people and may be reworded.
  • violations[] appears only on validation_failed, for a field of the body or a parameter.
  • A 5xx never carries details: quote the requestId when you contact support.
  • New codes may be added within v1. Treat an unknown code by its HTTP status.

Codes#

HTTP code When
400 validation_failed A bad body or parameter, unreadable JSON, pageSize over 200, a date outside 2000-01-01..2037-12-31, a range too long, an unknown event code, a code not enabled at the institution, an employee who is not a member there or whose membership ended before the event's business date, an eventTime more than 300 s ahead, a malformed Idempotency-Key
400 idempotency_required POST /integration/events without an Idempotency-Key
400 event_too_old An event's business date more than 62 days before today's (on a create, on the target of a correction or a void, and on a correction's new time)
401 invalid_api_key, key_revoked, key_expired See Authentication
403 ip_not_allowed See Authentication
403 scope_missing The key lacks the scope; the message names it
403 institution_not_allowed An institutionId outside the key; an employee write for a person with an active membership outside a key that lists institutions
403 not_api_event Correcting or voiding an event the integration API did not create
403 admin_linked_employee Changing the status of a protected employee record
404 not_found An unknown id, a resource outside the key, an unknown route
405 method_not_allowed A method the route does not have
406 not_acceptable An Accept header that excludes JSON; refused before the request runs, so a write writes nothing
409 conflict The event is no longer active (already corrected or voided), the membership already exists, an archived institution, a duplicate value
409 idempotency_in_progress See Idempotency
415 unsupported_media_type A body that is not application/json
422 idempotency_mismatch See Idempotency
429 rate_limited See Rate limits
500 internal_error A bug on the server; report the requestId
503 unavailable The server could not reach its data store or was too busy; nothing was changed, retry later

What to do#

Answer Do
400 Fix the request; violations[] names the fields. Retrying unchanged gets the same answer
401 Check the key; if it was rotated or revoked, ask the administrator for the current one
403, 404 Check the key's scopes and institutions with GET /integration/key
409 conflict Read the resource again: someone else changed it, or it already exists
409 idempotency_in_progress Retry with the same Idempotency-Key after Retry-After
429 Wait Retry-After seconds, then retry
500 Report the requestId to dev@mask.ba
503, a timeout Retry with an increasing delay; on a write, with the same Idempotency-Key