Troubleshooting Your API Requests

Use the HTTP status and the machine-readable fields to choose an action. Do not parse diagnostic text.

REST error response

Partnership operation errors use a string code, required message, and optional details:

{
  "code": "ValidationError",
  "message": "Invalid input.",
  "details": [
    {
      "field": "date_from",
      "code": "required",
      "message": "This field is required."
    }
  ]
}

Authentication and request-processing errors use numeric code and error_message. Optional description is diagnostic text:

{
  "code": 1001,
  "error_message": "AUTH_INVALID_SIGNATURE",
  "description": "signature verification failed"
}

details can be an array, object or string. Each response has one top-level error, although validation details can describe several fields. For numeric rate limits, optional retry_after is an RFC 3339 timestamp; Retry-After is seconds. Do not confuse the two representations.

Rebate error_code

Rebate record error_code inside a successful response is a separate processing diagnostic, not an HTTP error.

HTTP status guide

HTTP	Interpretation
400	Invalid request, validation error, or documented campaign conflict/limit.
401	API-key/signature error or Partnership AuthenticationFailed; inspect the envelope.
403	PermissionDenied or AUTH_FORBIDDEN.
404	Resource unavailable or absent where declared by the operation.
429	Rate limit: Throttled or AUTH_RATE_LIMIT.
500	Partnership Error or SYSTEM_INTERNAL_ERROR.
502	SYSTEM_BAD_GATEWAY, numeric code 1.
503	SYSTEM_TEMPORARY_UNAVAILABLE, numeric code 2.
504	ServiceTransportError, a Partnership string code.

Use the selected operation's declared responses. Campaign conflicts are represented by supported HTTP 400 errors; HTTP 409 is not declared by the current operations.

Partnership error codes

Use the action for your operation: read actions also apply to the read-only affiliation POST. Write actions apply only to operations that change data. Each operation lists its supported error codes in API Reference.

HTTP status / code	What It Means	How to Fix It
400 / ValidationError	Request validation failed, including bad-request or conflict conditions returned as validation errors.	Reads: Do not retry unchanged. Correct the request using details, then sign the corrected request again. Writes: Correct the request using the schema and safe validation details; read current state first when a write outcome is uncertain.
400 / NotUnique	A campaign or campaign-link value conflicts with an existing value.	Choose a different unique value or read the existing campaign or link.
400 / ManyItems	A campaign or campaign-link limit was reached.	Review the existing campaigns or links and reuse an existing resource where possible. Do not retry the same create request until the limit has been resolved.
401 / AuthenticationFailed	A Partnership service rejected the authenticated request after request authentication. API-key and request-signature failures use the numeric authentication errors.	Check the request authorization context. When the response uses the numeric envelope, follow the action for its error_message.
403 / PermissionDenied	The authenticated identity cannot perform the operation or access the requested partner data.	Use credentials with the required Partnership permission and resource access.
404 / NotFound	The resource does not exist or is not available to the partner.	Verify the identifier and current resource list.
429 / Throttled	A Partnership operation rate limit was exceeded.	Slow down the request rate and honor Retry-After when it is returned.
500 / Error	A Partnership operation failed because a required service could not complete the request.	Reads: Retry the request with backoff. Writes: For an uncertain write, read current state before deciding whether to send another write.
504 / ServiceTransportError	A service required by the Partnership operation could not be reached or timed out.	Reads: Retry the request with exponential backoff. Writes: For an uncertain write, read the affected resource before deciding whether to send another write.

Authentication and request-processing codes

HTTP status / code	What It Means	How to Fix It
502 / 1 — SYSTEM_BAD_GATEWAY	The API could not complete the request to the Partnership service.	Reads: Retry the request with backoff. Writes: For an uncertain write, read current state before deciding whether to send another write.
503 / 2 — SYSTEM_TEMPORARY_UNAVAILABLE	A required service is temporarily unavailable or the request deadline was exceeded.	Reads: Retry the request with backoff. Writes: For an uncertain write, read current state before deciding whether to send another write.
500 / 3 — SYSTEM_INTERNAL_ERROR	The API encountered an unexpected internal error.	Reads: Retry the request with backoff. Writes: For an uncertain write, read current state before deciding whether to send another write.
401 / 1000 — AUTH_INVALID_API_KEY	The API key is invalid, expired, revoked, or not allowed for the request source.	Check the API key, its state, and its allowed source IP.
401 / 1001 — AUTH_INVALID_SIGNATURE	The request signature or signed timestamp is invalid.	Rebuild the signature from the exact request and a fresh timestamp.
403 / 1002 — AUTH_FORBIDDEN	The API key does not have a required operation scope.	Use an API key with the required Partnership scope.
429 / 1003 — AUTH_RATE_LIMIT	The authentication rate limit was exceeded.	Honor Retry-After and reduce request rate.
400 / 3001 — REQUEST_INVALID_PARAMETERS	Required headers or signed request data are malformed or inconsistent.	Correct the headers or signed values named by description, then sign the exact request again.

Best practices for handling errors

• •

  Branch on codes

  Branch on HTTP status and code; for numeric codes, also use the stable error_message name.

• •

  Do not parse text

  Treat message, description and diagnostic detail text as human-readable information, not a parsing interface.

• •

  Apply the retry rule

  Apply the code-specific retry rule. Errors are non-retryable by default.

• •

  Respect rate limits

  Slow down on rate limits and honor Retry-After when returned. See API Configuration and Limits for the shared partner budget and operation settings. No fixed polling interval or retry count is specified by this contract.

• •

  Be careful with writes

  Retry reads only as permitted by the returned error. After an uncertain write, read current state before another write.

Common scenarios and solutions

Scenario	Action
Invalid signature	Rebuild signed data from the exact method, path, query, body and fresh timestamp. Sign decoded payload bytes and use unpadded base64url.
Required parameter missing	Use ValidationError details or REQUEST_INVALID_PARAMETERS diagnostics to correct the request; sign the corrected request again.
Campaign create returns NotUnique	Read campaigns or links to check for an existing value, or choose another allowed unique value.
A read cannot find a resource	Verify the identifier against the current resource list available to your partner.
A rebate batch is processed but some amount was rejected	Inspect rejected amounts and individual rows; batch completion is not proof that every row was paid.
Report totals differ from a recent result elsewhere	Keep the same filters and re-read; report families update asynchronously.

Authentication and permission checklist

Use the five signing headers documented by Partnership: EXN-API-KEY, EXN-TIMESTAMP, EXN-SIGN-VERSION, EXN-DATA and EXN-SIGN. Use partnership.all:read for read access or partnership.all for read/write. The affiliation check is a read operation implemented with POST. See Partnership permissions.

Recovery after an unknown write outcome

1. 1
   Preserve the intended resource identifier or the input used for the create.
2. 2
   Read the affected resource or its current list.
3. 3
   Reconcile the returned state with the intended change.
4. 4
   Decide whether another write is needed. Do not assume a repeated create is a replay.

No idempotent writes

Partnership has no idempotent-write guarantee. The reserved signed idempotency_key is empty; an idempotency header does not prevent duplicate execution.