Guides
Error and Idempotency Rules
Understand the public error envelope, submit retry safety, and when to create or reuse jobs.
Error and Idempotency Rules
This page covers the two rules most backend integrations rely on during failure handling: the shared response envelope and idempotent submit retries.
Error envelope
Morface public API responses follow:
{
"code": -1,
"message": "human-readable failure reason"
}code: 0 indicates success. code: -1 indicates an application-level failure response.
Common failure classes
| Area | Example |
|---|---|
| Auth | Missing, malformed, revoked, or expired API key |
| Validation | Missing required media or unsupported input contract |
| Ownership | Reading or cancelling a job owned by another user |
| Retry conflict | Reusing an Idempotency-Key with a different request body |
Idempotency scope
The submit route:
POST /api/v1/jobs/submit/{jobType}In practice, most clients should treat:
https://www.morface.ai/api/v1as the shared base URL and derive the submit URL from job_type.
accepts:
Idempotency-Key: your-stable-submit-keyThe scope is effectively:
user + route + idempotency keyBehavior
- Same key + same body: returns the original response
- Same key + different body: returns
409 - No key: each retry may create a new job
- Retention window: 24 hours
Retry strategy
Use an idempotency key when:
- your backend automatically retries on timeouts
- you submit through background workers
- you need crash-safe replay after a transient network failure
Do not reuse the same key for semantically different jobs.
Operational recommendation
- Generate one stable key per logical submit attempt.
- Persist the key alongside your own job record.
- Reuse it only when the request body is identical.