Skip to main content

API Reference & Error Codes

This page covers the error codes specific to API authentication, how to manage API keys, and the technical specifications of the HMAC signature scheme.

API Authentication Error Codes​

When the server rejects an API request during the validation pipeline, it returns one of the following error codes. The pipeline evaluates in order -- the first failing check determines the error response.

CodeNameHTTPDescription
GA2001API_KEY_REQUIRED401The X-Api-Key header is missing from the request.
GA2002SIGNATURE_REQUIRED401The X-Signature header is missing from the request.
GA2011API_KEY_INVALID401The API key was not found or has an invalid format. Verify you are using the correct key.
GA2012SIGNATURE_INVALID401HMAC signature verification failed. The computed signature does not match X-Signature. Check your canonical message construction and secret.
GA2013TIMESTAMP_EXPIRED401The request timestamp is outside the 60-second acceptance window, or the nonce has already been used. Ensure your server clock is NTP-synchronized.
GA2021API_KEY_DISABLED403The API key has been disabled by a workspace administrator. Contact your workspace owner.
GA2022IP_NOT_ALLOWED403The client IP address is not in the API key's IP whitelist. Add your server's IP in the portal.
GA2024SCOPE_DENIED403The API key does not have the required permission scope for this operation.
GA2032WORKSPACE_NOT_FOUND404The workspace associated with this API key was not found. The workspace may have been deleted.
GA2034WORKSPACE_NOT_MEMBER403The user associated with this API key is not a member of the target workspace.
Debugging authentication failures

Start by checking the HTTP status code and the code field in the response body. Work through the validation pipeline in order: if you see GA2013, fix your timestamp or nonce before investigating signature issues. The most common cause of GA2012 is inconsistent JSON serialization between the hash computation and the actual request body.

API Key Management​

API keys are managed through the Elaypay dashboard by workspace owners. You can create, view, revoke, and regenerate keys from the workspace settings page.

API Key Format​

API keys follow a prefixed format that indicates the environment:

PrefixEnvironmentExample
sk_live_Productionsk_live_abc123def456ghi789
sk_test_Sandbox / Testingsk_test_xyz987wvu654tsr321
Secret visibility

The API secret is shown only once -- at the moment of creation or regeneration. If you lose the secret, you must regenerate it. There is no way to retrieve a previously issued secret.

Key Lifecycle​

  Created (active)
       │
       ├── Regenerate secret → new secret, same key ID
       │
       └── Revoke → permanently disabled (GA2021)

Configuration Options​

When creating or updating an API key, you can configure:

  • Scopes -- Restrict which API operations the key can perform. If a request requires a scope the key does not have, the server returns GA2024.
  • IP whitelist -- Restrict which IP addresses can use the key. Requests from unlisted IPs receive GA2022. Leave empty to allow all IPs.
  • Description -- A human-readable label to help you identify the key's purpose.

Technical Specifications​

ParameterValue
Signature algorithmHMAC-SHA256
Body hash algorithmSHA-256 (hex-encoded, lowercase)
Signature encodingBase64 (standard, with padding)
Timestamp formatUnix epoch seconds (UTC)
Timestamp tolerance60 seconds (server rejects if |now - timestamp| > 60)
Nonce formatAny unique string; UUID v4 recommended
Nonce uniqueness enforcementServer-side; unique within the timestamp window
Empty body hashe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Canonical message formatmethod\npath\ntimestamp\nnonce\nbodyHash
Path in canonical messageRequest path only (no scheme, host, or query string)

Rate Limits​

API endpoints may enforce rate limits depending on the operation. When a rate limit is exceeded, the server returns HTTP 429 Too Many Requests. The response includes a Retry-After header indicating how many seconds to wait before retrying.

Request Size Limits​

LimitValue
Maximum request body size1 MB
Maximum URL length8,192 characters

Troubleshooting Guide​

Below are the most frequent issues integrators encounter, along with diagnostic steps.

GA2012: Signature Invalid​

This is the most common error. Walk through this checklist:

  1. Body hash mismatch. Print the exact byte string you are hashing and compare it to the exact byte string your HTTP library sends. Watch for differences in whitespace, key ordering, or character encoding.
  2. Wrong path. The canonical message uses the request path only -- no scheme (https://), no host, no query string. For /api/v1/wallets?page=0, use /api/v1/wallets.
  3. Newline characters. Ensure you are using \n (LF, 0x0A) as the separator. Some platforms default to \r\n (CRLF), which produces a different hash.
  4. Secret encoding. The API secret is a UTF-8 string. Do not Base64-decode it before using it as the HMAC key -- use the raw string.
  5. Base64 output. The signature must be standard Base64 (with +, /, and = padding). Do not use Base64-URL encoding.

GA2013: Timestamp Expired​

  1. Clock skew. Run date -u +%s on your server and compare against a known NTP source. If the difference exceeds 60 seconds, synchronize your clock.
  2. Nonce reuse. The same error code is returned for duplicate nonces. If your clock is correct, ensure you generate a fresh UUID for every request.
  3. Cached timestamps. If you compute the timestamp once and reuse it across multiple requests (e.g., in a batch loop), requests near the end of the batch may exceed the 60-second window.

GA2021: API Key Disabled​

An administrator has disabled this key via the portal. Check with your workspace owner. Once disabled, a key cannot be re-enabled -- you must create a new one.

GA2022: IP Not Allowed​

Your server's outbound IP does not match the whitelist configured for this API key. If your server is behind a load balancer or NAT gateway, use the external IP visible to the Elaypay API. You can check this with curl ifconfig.me.

Security Best Practices​

  1. Store secrets securely. Use a secrets manager (HashiCorp Vault, AWS Secrets Manager, etc.) rather than environment variables or configuration files checked into version control.

  2. Rotate secrets periodically. Use the regenerate endpoint to issue a new secret. Coordinate the rotation to update your servers before the old secret is invalidated.

  3. Use IP whitelisting. Restrict API key usage to your known server IP addresses. This prevents key misuse even if the secret is compromised.

  4. Apply least-privilege scopes. Only grant the scopes each key actually needs. Create separate keys for separate services or use cases.

  5. Synchronize your clock. Use NTP to keep your server's clock within a few seconds of UTC. The 60-second timestamp window is generous, but clock drift beyond that causes persistent GA2013 errors.

  6. Never expose secrets client-side. API keys and secrets must only be used from server-side code. Never embed them in frontend JavaScript, mobile apps, or client-side configuration.