Check the connection and the key
Confirms that the service is reachable and that the supplied API key is valid.
The example applies to the demo environment only.
Request
curl -i -X GET "https://sandbox.api.earhiva.mk/api/integration/v1/ping" \
-H "X-Api-Key: <YOUR KEY>" \
-H "X-Software-Id: <NAME AND VERSION OF YOUR APPLICATION>"Every call carries X-Api-Key with a key that has the IntegrationApi scope, and X-Software-Id with the name and version of your software. How to request a key is on Authentication.
Parameters
All parameters (1)
| Parameter | In | Type | Presence | Description |
|---|---|---|---|---|
X-Software-Id | header | string | always | Identifier of the calling software, e.g. SSBFocus/4.2.1. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008. |
Error codes
EARH-1001 · EARH-1002 · EARH-1003 · EARH-1004 · EARH-1005 · EARH-1006 · EARH-1008 · EARH-1010 · EARH-1011
The full list of codes, what each means and what to do, is in the Error catalogue.
Responses
Section titled “ Responses ”The service is up and the key is valid.
{
"ok": true,
"keyValid": true,
"serverTime": "2026-08-26T23:21:51+02:00"
}All fields in the body (3)
| Field | Type | Presence | Description |
|---|---|---|---|
ok | boolean | always | Always true — a call that reaches this answer has passed the gate. |
keyValid | boolean | always | Always true — an invalid key never reaches this answer, it is refused with a 401. |
serverTime | string · date-time | always | Current time on our server, in its local offset. Useful for spotting a clock difference on your side. |
The X-Software-Id header is missing — EARH-1008.
{
"type": "https://earhiva.mk/errors/EARH-1008",
"title": "X-Software-Id header is missing.",
"status": 400,
"code": "EARH-1008"
}All fields in the body (6)
| Field | Type | Presence | Description |
|---|---|---|---|
type | string | always | Address of this code in the error catalogue (RFC 7807). |
title | string | always | Short, stable English summary of the error — the same string that appears in your log. |
status | integer · int32 | always | HTTP status code, repeated in the body (RFC 7807). |
detail | string | nullable | What went wrong in this particular call, when there is more to say than the title. Absent when the title already says everything. |
code | string | always | The EARH-xxxx code. This is the contract: match on it, not on the text. |
eventId | string | nullable | Only on EARH-9000. Quote it when reporting the problem — it is the same reference we record in our log, so one number identifies the event on both sides. |
The API key is missing, unknown, expired or revoked — EARH-1001, EARH-1002, EARH-1003. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.
The caller’s address is outside the allowed list, the key does not carry the IntegrationApi scope, the organization’s plan does not include integration access, or the key has been switched off by its owner — EARH-1004, EARH-1005, EARH-1010, EARH-1011. The last two are returned on every call and carry no Retry-After: waiting does not change the state. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.
The traffic limit for this key has been reached — EARH-1006. The response carries Retry-After. The limit is counted per key, and its size comes from the organization’s plan. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.
Unexpected error on our side — EARH-9000. The body carries eventId; quote it when reporting the problem. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.